@ontrails/warden 1.0.0-beta.3 → 1.0.0-beta.30

package/src/trails/wrap-rule.ts

@@ -0,0 +1,214 @@
+/**
+ * Factory that wraps a WardenRule as a trail.
+ *
+ * Keeps each rule trail file minimal — just the import + examples.
+ */
+
+import { InternalError, trail, Result } from '@ontrails/core';
+import type { Trail } from '@ontrails/core';
+
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  TopoAwareWardenRule,
+  WardenRule,
+} from '../rules/types.js';
+import { getWardenRuleMetadata } from '../rules/metadata.js';
+import {
+  projectAwareRuleInput,
+  ruleInput,
+  ruleOutput,
+  topoAwareRuleInput,
+} from './schema.js';
+import type {
+  ProjectAwareRuleInput,
+  RuleInput,
+  RuleOutput,
+  TopoAwareRuleInput,
+} from './schema.js';
+
+interface WrapRuleOptions {
+  /** The existing warden rule to wrap. */
+  readonly rule: WardenRule;
+  /** Trail examples for testing and documentation. */
+  readonly examples: Trail<RuleInput, RuleOutput>['examples'];
+}
+
+interface WrapProjectAwareRuleOptions {
+  /** The existing project-aware warden rule to wrap. */
+  readonly rule: ProjectAwareWardenRule;
+  /** Trail examples for testing and documentation. */
+  readonly examples: Trail<ProjectAwareRuleInput, RuleOutput>['examples'];
+}
+
+const buildRuleMeta = (rule: WardenRule | TopoAwareWardenRule) => {
+  const metadata = getWardenRuleMetadata(rule);
+  return {
+    category: 'governance',
+    ...(metadata ? { warden: metadata } : {}),
+    severity: rule.severity,
+  };
+};
+
+const buildProjectContext = (input: ProjectAwareRuleInput): ProjectContext => ({
+  ...(input.contourReferencesByName
+    ? {
+        contourReferencesByName: new Map(
+          Object.entries(input.contourReferencesByName)
+        ),
+      }
+    : {}),
+  ...(input.crudTableIds ? { crudTableIds: new Set(input.crudTableIds) } : {}),
+  ...(input.crudCoverageByEntity
+    ? {
+        crudCoverageByEntity: new Map(
+          Object.entries(input.crudCoverageByEntity).map(
+            ([entityId, operations]) => [
+              entityId,
+              new Set(operations) as ReadonlySet<string>,
+            ]
+          )
+        ),
+      }
+    : {}),
+  ...(input.knownContourIds
+    ? { knownContourIds: new Set(input.knownContourIds) }
+    : {}),
+  ...(input.importResolutionsByFile
+    ? {
+        importResolutionsByFile: new Map(
+          Object.entries(input.importResolutionsByFile)
+        ),
+      }
+    : {}),
+  ...(input.documentedImportResolutionsByFile
+    ? {
+        documentedImportResolutionsByFile: new Map(
+          Object.entries(input.documentedImportResolutionsByFile)
+        ),
+      }
+    : {}),
+  ...(input.publicWorkspaces
+    ? { publicWorkspaces: new Map(Object.entries(input.publicWorkspaces)) }
+    : {}),
+  knownTrailIds: input.knownTrailIds
+    ? new Set(input.knownTrailIds)
+    : new Set<string>(),
+  ...(input.composeTargetTrailIds
+    ? { composeTargetTrailIds: new Set(input.composeTargetTrailIds) }
+    : {}),
+  ...(input.knownResourceIds
+    ? { knownResourceIds: new Set(input.knownResourceIds) }
+    : {}),
+  ...(input.knownSignalIds
+    ? { knownSignalIds: new Set(input.knownSignalIds) }
+    : {}),
+  ...(input.onTargetSignalIds
+    ? { onTargetSignalIds: new Set(input.onTargetSignalIds) }
+    : {}),
+  ...(input.reconcileTableIds
+    ? { reconcileTableIds: new Set(input.reconcileTableIds) }
+    : {}),
+  ...(input.trailIntentsById
+    ? { trailIntentsById: new Map(Object.entries(input.trailIntentsById)) }
+    : {}),
+  ...(input.topoTrailIds ? { topoTrailIds: new Set(input.topoTrailIds) } : {}),
+});
+
+/**
+ * Wrap an existing `WardenRule` as a trail with typed input/output.
+ *
+ * The trail ID follows the pattern `warden.rule.<rule-name>`.
+ */
+export function wrapRule(
+  options: WrapProjectAwareRuleOptions
+): Trail<ProjectAwareRuleInput, RuleOutput>;
+export function wrapRule(
+  options: WrapRuleOptions
+): Trail<RuleInput, RuleOutput>;
+export function wrapRule(
+  options: WrapRuleOptions | WrapProjectAwareRuleOptions
+): Trail<RuleInput, RuleOutput> | Trail<ProjectAwareRuleInput, RuleOutput> {
+  const { rule, examples } = options;
+  const isProjectAware = 'checkWithContext' in rule;
+
+  if (isProjectAware) {
+    const projectAwareRule = rule as ProjectAwareWardenRule;
+    return trail(`warden.rule.${rule.name}`, {
+      blaze: (input: ProjectAwareRuleInput) => {
+        const diagnostics = projectAwareRule.checkWithContext(
+          input.sourceCode,
+          input.filePath,
+          buildProjectContext(input)
+        );
+        return Result.ok({ diagnostics: [...diagnostics] });
+      },
+      description: rule.description,
+      examples: examples as Trail<
+        ProjectAwareRuleInput,
+        RuleOutput
+      >['examples'],
+      input: projectAwareRuleInput,
+      intent: 'read',
+      meta: buildRuleMeta(rule),
+      output: ruleOutput,
+    });
+  }
+
+  return trail(`warden.rule.${rule.name}`, {
+    blaze: (input: RuleInput) => {
+      const diagnostics = rule.check(input.sourceCode, input.filePath);
+      return Result.ok({ diagnostics: [...diagnostics] });
+    },
+    description: rule.description,
+    examples: examples as Trail<RuleInput, RuleOutput>['examples'],
+    input: ruleInput,
+    intent: 'read',
+    meta: buildRuleMeta(rule),
+    output: ruleOutput,
+  });
+}
+
+interface WrapTopoRuleOptions {
+  /** The existing topo-aware warden rule to wrap. */
+  readonly rule: TopoAwareWardenRule;
+  /** Trail examples for testing and documentation. */
+  readonly examples: Trail<TopoAwareRuleInput, RuleOutput>['examples'];
+}
+
+/**
+ * Wrap an existing `TopoAwareWardenRule` as a trail.
+ *
+ * Mirrors `wrapRule` for the per-topo dispatch path. Topo-aware rules run
+ * once per topo against the compiled runtime graph rather than per file,
+ * so the trail accepts the live `Topo` as input.
+ */
+export const wrapTopoRule = (
+  options: WrapTopoRuleOptions
+): Trail<TopoAwareRuleInput, RuleOutput> => {
+  const { rule, examples } = options;
+  return trail(`warden.rule.${rule.name}`, {
+    blaze: async (input: TopoAwareRuleInput) => {
+      try {
+        const diagnostics = await rule.checkTopo(input.topo, {
+          graph: input.graph,
+        });
+        return Result.ok({ diagnostics: [...diagnostics] });
+      } catch (error) {
+        const cause = error instanceof Error ? error : new Error(String(error));
+        return Result.err(
+          new InternalError(
+            `Topo-aware rule "${rule.name}" threw while inspecting topo: ${cause.message}`,
+            { cause }
+          )
+        );
+      }
+    },
+    description: rule.description,
+    examples,
+    input: topoAwareRuleInput,
+    intent: 'read',
+    meta: buildRuleMeta(rule),
+    output: ruleOutput,
+  });
+};

package/src/workspaces.ts

@@ -0,0 +1,238 @@
+/**
+ * Workspace-manifest discovery for Warden project-aware rules.
+ */
+
+import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+export interface WardenPublicWorkspace {
+  readonly name: string;
+  readonly rootDir: string;
+  readonly packageJsonPath: string;
+  readonly hasExports: boolean;
+  readonly bin?: Readonly<Record<string, string>> | undefined;
+  readonly exportTargets?: Readonly<Record<string, string>> | undefined;
+  readonly files?: readonly string[] | undefined;
+}
+
+interface RootManifest {
+  readonly workspaces?: unknown;
+}
+
+interface PackageManifest {
+  readonly bin?: unknown;
+  readonly exports?: unknown;
+  readonly files?: unknown;
+  readonly name?: unknown;
+  readonly private?: unknown;
+}
+
+const normalizePath = (path: string): string => path.replaceAll('\\', '/');
+
+const normalizeRealPath = (path: string): string => {
+  try {
+    return normalizePath(realpathSync(path));
+  } catch {
+    return normalizePath(resolve(path));
+  }
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value && typeof value === 'object' && !Array.isArray(value));
+
+const readJson = <T>(path: string): T | undefined => {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as T;
+  } catch {
+    return undefined;
+  }
+};
+
+const workspacePatternsFromManifest = (
+  manifest: RootManifest | undefined
+): readonly string[] => {
+  const { workspaces } = manifest ?? {};
+  if (Array.isArray(workspaces)) {
+    return workspaces.filter(
+      (pattern): pattern is string => typeof pattern === 'string'
+    );
+  }
+
+  const packages = isRecord(workspaces) ? workspaces['packages'] : undefined;
+  return Array.isArray(packages)
+    ? packages.filter(
+        (pattern): pattern is string => typeof pattern === 'string'
+      )
+    : [];
+};
+
+const workspaceDirsForPattern = (
+  rootDir: string,
+  pattern: string
+): readonly string[] => {
+  if (!pattern.endsWith('/*')) {
+    const workspaceDir = join(rootDir, pattern);
+    return existsSync(workspaceDir) ? [workspaceDir] : [];
+  }
+
+  const groupDir = join(rootDir, pattern.slice(0, -2));
+  if (!existsSync(groupDir)) {
+    return [];
+  }
+
+  return readdirSync(groupDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => join(groupDir, entry.name))
+    .toSorted();
+};
+
+const packageLocalName = (name: string): string =>
+  name.split('/').at(-1) ?? name;
+
+const normalizeBin = (
+  name: string,
+  value: unknown
+): Readonly<Record<string, string>> | undefined => {
+  if (typeof value === 'string') {
+    return { [packageLocalName(name)]: value };
+  }
+  if (!isRecord(value)) {
+    return undefined;
+  }
+
+  const entries = Object.entries(value).filter(
+    (entry): entry is [string, string] => typeof entry[1] === 'string'
+  );
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+};
+
+const normalizeFiles = (value: unknown): readonly string[] | undefined => {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+
+  const files = value.filter(
+    (entry): entry is string => typeof entry === 'string'
+  );
+  return files.length > 0 ? files : undefined;
+};
+
+const resolveExportTarget = (
+  target: unknown,
+  depth = 0
+): string | undefined => {
+  if (typeof target === 'string') {
+    return target;
+  }
+  if (!isRecord(target) || depth > 8) {
+    return undefined;
+  }
+
+  for (const condition of ['bun', 'import', 'default', 'require'] as const) {
+    const conditionalTarget = target[condition];
+    const resolvedTarget = resolveExportTarget(conditionalTarget, depth + 1);
+    if (resolvedTarget) {
+      return resolvedTarget;
+    }
+  }
+  return undefined;
+};
+
+const exportSpecifierFromKey = (
+  packageName: string,
+  key: string
+): string | undefined => {
+  if (key === '.') {
+    return packageName;
+  }
+  if (!key.startsWith('./') || key.includes('*')) {
+    return undefined;
+  }
+  return `${packageName}/${key.slice(2)}`;
+};
+
+const normalizeExportTargets = (
+  packageDir: string,
+  packageName: string,
+  exportsValue: unknown
+): Readonly<Record<string, string>> | undefined => {
+  if (!isRecord(exportsValue)) {
+    return undefined;
+  }
+
+  const targets: Record<string, string> = {};
+  for (const [key, value] of Object.entries(exportsValue)) {
+    const specifier = exportSpecifierFromKey(packageName, key);
+    const target = resolveExportTarget(value);
+    if (!specifier || !target) {
+      continue;
+    }
+    targets[specifier] = normalizeRealPath(join(packageDir, target));
+  }
+
+  return Object.keys(targets).length > 0 ? targets : undefined;
+};
+
+const publicWorkspaceFromManifest = (
+  packageJsonPath: string,
+  manifest: PackageManifest
+): WardenPublicWorkspace | undefined => {
+  if (typeof manifest.name !== 'string') {
+    return undefined;
+  }
+  if (!manifest.name.startsWith('@ontrails/')) {
+    return undefined;
+  }
+  if (manifest.private === true) {
+    return undefined;
+  }
+
+  const packageDir = dirname(packageJsonPath);
+  const bin = normalizeBin(manifest.name, manifest.bin);
+  const exportTargets = normalizeExportTargets(
+    packageDir,
+    manifest.name,
+    manifest.exports
+  );
+  const files = normalizeFiles(manifest.files);
+
+  return {
+    ...(bin ? { bin } : {}),
+    ...(exportTargets ? { exportTargets } : {}),
+    ...(files ? { files } : {}),
+    hasExports: manifest.exports !== undefined,
+    name: manifest.name,
+    packageJsonPath: normalizeRealPath(packageJsonPath),
+    rootDir: normalizeRealPath(dirname(packageJsonPath)),
+  };
+};
+
+export const collectPublicWorkspaces = (
+  rootDir: string
+): ReadonlyMap<string, WardenPublicWorkspace> => {
+  const normalizedRoot = normalizeRealPath(rootDir);
+  const rootManifest = readJson<RootManifest>(
+    join(normalizedRoot, 'package.json')
+  );
+  const workspaces = new Map<string, WardenPublicWorkspace>();
+
+  for (const pattern of workspacePatternsFromManifest(rootManifest)) {
+    for (const workspaceDir of workspaceDirsForPattern(
+      normalizedRoot,
+      pattern
+    )) {
+      const packageJsonPath = join(workspaceDir, 'package.json');
+      const manifest = readJson<PackageManifest>(packageJsonPath);
+      if (!manifest) {
+        continue;
+      }
+
+      const workspace = publicWorkspaceFromManifest(packageJsonPath, manifest);
+      if (workspace) {
+        workspaces.set(workspace.name, workspace);
+      }
+    }
+  }
+
+  return workspaces;
+};

package/.turbo/turbo-build.log

@@ -1 +0,0 @@
-$ tsc -b

package/.turbo/turbo-lint.log

@@ -1,3 +0,0 @@
-$ oxlint ./src
-Found 0 warnings and 0 errors.
-Finished in 46ms on 30 files with 93 rules using 24 threads.

package/.turbo/turbo-typecheck.log

@@ -1 +0,0 @@
-$ tsc --noEmit

package/dist/cli.d.ts

@@ -1,46 +0,0 @@
-/**
- * Warden CLI command runner.
- *
- * Scans TypeScript files, runs all warden rules, optionally checks drift,
- * and returns a structured report.
- */
-import type { Topo } from '@ontrails/core';
-import type { DriftResult } from './drift.js';
-import type { WardenDiagnostic } from './rules/types.js';
-/**
- * Options for the warden CLI runner.
- */
-export interface WardenOptions {
-    /** Root directory to scan for TypeScript files. Defaults to cwd. */
-    readonly rootDir?: string | undefined;
-    /** Only run lint rules, skip drift detection */
-    readonly lintOnly?: boolean | undefined;
-    /** Only run drift detection, skip lint rules */
-    readonly driftOnly?: boolean | undefined;
-    /** App topology for drift detection. When provided, enables real surface lock comparison. */
-    readonly topo?: Topo | undefined;
-}
-/**
- * Result of a warden run.
- */
-export interface WardenReport {
-    /** All diagnostics from lint rules */
-    readonly diagnostics: readonly WardenDiagnostic[];
-    /** Count of error-severity diagnostics */
-    readonly errorCount: number;
-    /** Count of warn-severity diagnostics */
-    readonly warnCount: number;
-    /** Drift detection result, or null if skipped */
-    readonly drift: DriftResult | null;
-    /** Whether the warden run passed (no errors, no drift) */
-    readonly passed: boolean;
-}
-/**
- * Run all warden checks and return a structured report.
- */
-export declare const runWarden: (options?: WardenOptions) => Promise<WardenReport>;
-/**
- * Format a warden report as a human-readable string.
- */
-export declare const formatWardenReport: (report: WardenReport) => string;
-//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAS9C,OAAO,KAAK,EAGV,gBAAgB,EAEjB,MAAM,kBAAkB,CAAC;AAE1B;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC,gDAAgD;IAChD,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACzC,6FAA6F;IAC7F,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,QAAQ,CAAC,WAAW,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAClD,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IACnC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAyLD;;GAEG;AACH,eAAO,MAAM,SAAS,GACpB,UAAS,aAAkB,KAC1B,OAAO,CAAC,YAAY,CAqBtB,CAAC;AAsDF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,YAAY,KAAG,MAmBzD,CAAC"}