@ontrails/source 1.0.0-beta.41

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# @ontrails/source
+
+## 1.0.0-beta.41
+
+## 1.0.0-beta.40
+
+### Minor Changes
+
+- [`35cbe28`](https://github.com/outfitter-dev/trails/commit/35cbe289db46539b3689dbf6cf8ab0e5d9a1b09c): Found `@ontrails/source` as the shared source-code AST kernel for parsing,
+  walking, locations, edits, literals, and generic Trails syntax recognition.
+  Warden, Regrade, Wayfinder, and the Trails operator now import those shared
+  mechanics from `@ontrails/source`; the legacy Warden AST route is removed by the
+  stacked hard cutover.
+
+### Patch Changes
+
+- [`3531b58`](https://github.com/outfitter-dev/trails/commit/3531b58ba5320753d6d2594257ef71bc950d28a1): Add the advisory captured-kernel Warden rule for ownership review when a public
+  subpath re-exports package internals and multiple production workspaces consume
+  that subpath, including import-then-export barrels that preserve the internal
+  binding through a local alias or default export.
+
+  Expose typed import-kind inspection from `@ontrails/source` so project rules
+  can keep erased type bindings separate from runtime exports.
+
+- [`10f2492`](https://github.com/outfitter-dev/trails/commit/10f24928d3bc9d995abf7aa261ecf515c295855d): Own the `wayfind.outline` implementation in the Trails operator app while preserving the existing `trails wayfind file <file> --outline` CLI and MCP composition behavior, and document `@ontrails/source` as the operator's live-source analysis kernel.
+- [`35e5fed`](https://github.com/outfitter-dev/trails/commit/35e5fedd228e498783f479f0dd502e2f3ec772b8): Fold the Wayfinder graph-read catalog into `@ontrails/topography`. Wayfind
+  remains the product, trail-id, CLI, and MCP brand, but there is no longer an
+  `@ontrails/wayfinder` package to install or import. Programmatic consumers
+  should move imports such as `wayfinderTopo`, `wayfindOverviewTrail`,
+  `loadWayfinderArtifacts`, and the Wayfinder filter/provenance types to
+  `@ontrails/topography`.
+
+  Expose that package move as a governed Regrade transition so exact
+  `@ontrails/wayfinder` imports can move safely while product vocabulary and near
+  routes remain unchanged for review. Regrade routes package manifests through
+  structured review instead of rewriting dependency keys as plain text.
+
+  The Trails operator now reads all `wayfind.*` query trails and artifact helpers
+  from `@ontrails/topography` while preserving the existing CLI/MCP schemas,
+  route IDs, output shapes, and internal trail visibility.
+
+- [`3a65ae3`](https://github.com/outfitter-dev/trails/commit/3a65ae363e05b7589f4a9876da4346886353b48c): Rename the durable graph substrate package from `@ontrails/topographer` to
+  `@ontrails/topography` after folding Wayfind graph queries into that owner.
+
+  Update imports to `@ontrails/topography` or
+  `@ontrails/topography/backend-support`. The pre-1.0 cutover does not ship a
+  compatibility package. TopoGraph, lock, topo-store, semantic diff, and Wayfind
+  APIs keep their existing contracts, and the `trails wayfind` CLI and MCP names
+  remain unchanged.
+
+  The governed package-route transition moves legacy `@ontrails/wayfinder`
+  imports directly to `@ontrails/topography`; it does not emit the retired
+  intermediate `@ontrails/topographer` route.

package/README.md

@@ -0,0 +1,80 @@
+# @ontrails/source
+
+Shared source-code machinery for Trails packages and repo tooling.
+
+`source` means source code: TypeScript and JavaScript text parsed into an OXC AST. It does not mean activation source, signal source, data source, event source, or execution source.
+
+## What It Owns
+
+`@ontrails/source` owns reusable source-code mechanics:
+
+- AST node guards and accessors for the OXC node shapes Trails tooling uses.
+- `parse` and `parseWithDiagnostics` wrappers over `oxc-parser`.
+- `walk`, parent-aware walking, and scope-aware walking over `oxc-walker`.
+- Source locations, source edits, literal extraction, and generic Trails syntax recognition.
+- Generic trail/entity discovery helpers such as `findTrailDefinitions`, `findImplementationBodies`, `findEntityDefinitions`, and `isImplementationCall`.
+
+The package root is the public API. Import from `@ontrails/source`; there are no supported `/ast`, `/trails`, or `/utils` subpaths.
+
+## Package Admission Test
+
+`@ontrails/source` exists because the same source-code contract is reused by independent toolchain owners:
+
+- Warden uses it to implement source-static governance without owning the parser facade.
+- Regrade uses it for safe downstream source rewrites.
+- The Trails operator uses it to assemble live source-file outlines.
+- The `trails` operator uses it for draft promotion and version-lifecycle support.
+
+The package is admitted only for reusable source machinery with at least two independent toolchain owners and a genuinely shared contract. It must not absorb product verdicts, release plans, query semantics, rendering, Warden rule policy, Regrade engines, Topography artifact assembly, or Wayfinder answer composition.
+
+This boundary follows the package-worthiness rule in [ADR-0051: Package Ownership Follows Natural Altitude](../../docs/adr/0051-package-ownership-follows-natural-altitude.md): move code when the natural owner is above one consumer, not when a file merely feels crowded.
+
+## Examples
+
+Parse source and inspect trail declarations:
+
+```ts
+import { findTrailDefinitions, parse } from '@ontrails/source';
+
+const ast = parse(
+  'example.ts',
+  "import { trail } from '@ontrails/core';\nexport const show = trail('user.show', {});\n"
+);
+
+const trailIds = ast ? findTrailDefinitions(ast).map((trail) => trail.id) : [];
+```
+
+Walk source with parent context:
+
+```ts
+import { parse, walkWithParents } from '@ontrails/source';
+
+const ast = parse('example.ts', 'const value = trail("demo.show", {});\n');
+const callParents: string[] = [];
+
+if (ast) {
+  walkWithParents(ast, (node, context) => {
+    if (node.type === 'CallExpression') {
+      callParents.push(`${context.parent?.type ?? 'root'}:${String(context.key)}`);
+    }
+  });
+}
+```
+
+Apply source edits:
+
+```ts
+import { applySourceEdits, createSourceEdit } from '@ontrails/source';
+
+const updated = applySourceEdits('const name = "old";\n', [
+  createSourceEdit(14, 17, 'new'),
+]);
+```
+
+## Non-Goals
+
+- Warden rule policy and rule-specific facts remain in `@ontrails/warden`.
+- Regrade migration planning and execution remain in `@ontrails/regrade`.
+- Topography graph artifacts and outline assembly remain outside this package.
+- Wayfind query trails and answer rendering remain in `@ontrails/topography`.
+- Runtime Trails contracts remain in `@ontrails/core`.

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@ontrails/source",
+  "version": "1.0.0-beta.41",
+  "description": "Shared source-code AST parsing, walking, location, edit, literal, and Trails syntax helpers.",
+  "files": [
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "oxc-parser": "^0.121.0",
+    "oxc-walker": "^1.0.0"
+  }
+}

package/src/edits.ts

@@ -0,0 +1,57 @@
+/** Shared source-edit helpers. */
+
+import type { SourceEdit } from './nodes.js';
+
+export const createSourceEdit = (
+  start: number,
+  end: number,
+  replacement: string
+): SourceEdit => ({ end, replacement, start });
+
+export const validateSourceEdits = (
+  edits: readonly SourceEdit[],
+  sourceLength?: number
+): readonly SourceEdit[] => {
+  const ordered = [...edits].toSorted(
+    (left, right) => left.start - right.start
+  );
+  for (let i = 0; i < ordered.length; i += 1) {
+    const edit = ordered[i];
+    if (!edit) {
+      continue;
+    }
+    if (
+      !Number.isSafeInteger(edit.start) ||
+      !Number.isSafeInteger(edit.end) ||
+      edit.start < 0 ||
+      edit.end < edit.start ||
+      (sourceLength !== undefined && edit.end > sourceLength)
+    ) {
+      throw new Error(`Invalid source edit range ${edit.start}-${edit.end}.`);
+    }
+
+    const previous = ordered[i - 1];
+    if (previous && edit.start < previous.end) {
+      throw new Error(
+        `Overlapping source edits ${previous.start}-${previous.end} and ${edit.start}-${edit.end}.`
+      );
+    }
+  }
+
+  return ordered;
+};
+
+export const applySourceEdits = (
+  sourceCode: string,
+  edits: readonly SourceEdit[]
+): string => {
+  validateSourceEdits(edits, sourceCode.length);
+
+  return [...edits]
+    .toSorted((left, right) => right.start - left.start)
+    .reduce(
+      (output, edit) =>
+        output.slice(0, edit.start) + edit.replacement + output.slice(edit.end),
+      sourceCode
+    );
+};

package/src/index.ts

@@ -0,0 +1,24 @@
+export * from './nodes.js';
+export * from './parse.js';
+export * from './walk.js';
+export * from './scopes.js';
+export * from './locations.js';
+export * from './edits.js';
+export * from './literals.js';
+export type {
+  EntityDefinition,
+  FindEntityDefinitionsOptions,
+  FrameworkNamespaceContext,
+  TrailDefinition,
+} from './trails.js';
+export {
+  buildFrameworkNamespaceContext,
+  extractEntityDefinition,
+  extractTrailDefinition,
+  findEntityDefinitions,
+  findImplementationBodies,
+  findTrailDefinitions,
+  getImportSourceValue,
+  isImplementationCall,
+  isFrameworkNamespaceSource,
+} from './trails.js';

package/src/literals.ts

@@ -0,0 +1,226 @@
+/** Shared literal, string, and static property-key helpers. */
+
+import { isAstNode } from './nodes.js';
+import type { AstNode, StringLiteralNode } from './nodes.js';
+import { walk } from './walk.js';
+
+export const identifierName = (node: AstNode | undefined): string | null => {
+  if (node?.type !== 'Identifier') {
+    return null;
+  }
+  return (node as unknown as { name?: string }).name ?? null;
+};
+
+/** Check if a node is a string literal. */
+export const isStringLiteral = (
+  node: AstNode | undefined
+): node is StringLiteralNode => {
+  if (!node) {
+    return false;
+  }
+  if (node.type === 'StringLiteral') {
+    return true;
+  }
+  if (node.type === 'Literal') {
+    return typeof (node as unknown as { value?: unknown }).value === 'string';
+  }
+  return false;
+};
+
+/** Extract the string value from a string literal node. */
+export const getStringValue = (node: AstNode): string | null => {
+  const val = (node as unknown as { value?: unknown }).value;
+  return typeof val === 'string' ? val : null;
+};
+
+/**
+ * Best-effort resolution of `const NAME = 'value'` declarations via regex.
+ *
+ * Returns the string value if a simple `const <name> = '...'` or `"..."` is
+ * found in the source. Returns null for anything more complex. Shared between
+ * warden rules that need to resolve identifier references to signal / trail
+ * IDs at lint time.
+ */
+export const deriveConstString = (
+  name: string,
+  sourceCode: string
+): string | null => {
+  const pattern = new RegExp(
+    `const\\s+${name}\\s*=\\s*(?:'([^']*)'|"([^"]*)")`
+  );
+  const match = pattern.exec(sourceCode);
+  if (!match) {
+    return null;
+  }
+  return match[1] ?? match[2] ?? null;
+};
+
+/** Extract a string literal value, or null when the node is not a string. */
+export const extractStringLiteral = (
+  node: AstNode | undefined
+): string | null =>
+  node && isStringLiteral(node) ? getStringValue(node) : null;
+
+/**
+ * Extract the cooked value from a `TemplateLiteral` with no interpolations
+ * (e.g. `` `entity.fallback` ``). Template literals with `${...}` expressions
+ * cannot be resolved at lint time and return null.
+ *
+ * Shared helper used by rules that accept both string literals and simple
+ * backtick-literal IDs (e.g. `valid-describe-refs`).
+ */
+const getSingleQuasi = (node: AstNode): AstNode | null => {
+  const expressions =
+    (node['expressions'] as readonly AstNode[] | undefined) ?? [];
+  if (expressions.length > 0) {
+    return null;
+  }
+  const quasis = (node['quasis'] as readonly AstNode[] | undefined) ?? [];
+  return quasis.length === 1 ? (quasis[0] ?? null) : null;
+};
+
+export const extractPlainTemplateLiteral = (
+  node: AstNode | undefined
+): string | null => {
+  if (!node || node.type !== 'TemplateLiteral') {
+    return null;
+  }
+  const quasi = getSingleQuasi(node);
+  if (!quasi) {
+    return null;
+  }
+  const cooked = (quasi as unknown as { value?: { cooked?: unknown } }).value
+    ?.cooked;
+  return typeof cooked === 'string' ? cooked : null;
+};
+
+/**
+ * Extract a string value from either a string literal or a plain template
+ * literal (no `${...}` expressions). Returns null for anything else.
+ */
+export const extractStringOrTemplateLiteral = (
+  node: AstNode | undefined
+): string | null =>
+  extractStringLiteral(node) ?? extractPlainTemplateLiteral(node);
+
+export interface StringLiteralMatch {
+  readonly end: number;
+  readonly node: AstNode;
+  readonly start: number;
+  readonly value: string;
+}
+
+export const findStringLiterals = (
+  ast: AstNode,
+  predicate?: (value: string, node: AstNode) => boolean
+): StringLiteralMatch[] => {
+  const matches: StringLiteralMatch[] = [];
+
+  walk(ast, (node) => {
+    if (!isStringLiteral(node)) {
+      return;
+    }
+
+    const value = getStringValue(node);
+    if (value === null) {
+      return;
+    }
+
+    if (predicate && !predicate(value, node)) {
+      return;
+    }
+
+    matches.push({
+      end: node.end,
+      node,
+      start: node.start,
+      value,
+    });
+  });
+
+  return matches;
+};
+
+/** Extract the first string argument from a CallExpression. */
+export const extractFirstStringArg = (node: AstNode): string | null => {
+  if (node.type !== 'CallExpression') {
+    return null;
+  }
+
+  const args = node['arguments'] as readonly AstNode[] | undefined;
+  const [firstArg] = args ?? [];
+  return extractStringLiteral(firstArg);
+};
+
+export const extractBindingName = (
+  node: AstNode | undefined
+): string | null => {
+  if (!node) {
+    return null;
+  }
+  if (node.type === 'Identifier') {
+    return identifierName(node);
+  }
+  if (node.type === 'AssignmentPattern') {
+    return identifierName((node as unknown as { left?: AstNode }).left);
+  }
+  return null;
+};
+
+export const staticPropertyKeyName = (key: AstNode): string | null => {
+  if (key.type === 'Identifier') {
+    return (key as unknown as { name?: string }).name ?? null;
+  }
+  return isStringLiteral(key) ? getStringValue(key) : null;
+};
+
+export const propertyKeyName = (prop: AstNode): string | null => {
+  if (prop.type !== 'Property') {
+    return null;
+  }
+  const { computed } = prop as unknown as { computed?: boolean };
+  if (computed) {
+    return null;
+  }
+  const key = prop.key as AstNode | undefined;
+  return key ? staticPropertyKeyName(key) : null;
+};
+
+/** Find a Property node by key name inside an ObjectExpression config. */
+export const findConfigProperty = (
+  config: AstNode,
+  propertyName: string
+): AstNode | null => {
+  if (config.type !== 'ObjectExpression') {
+    return null;
+  }
+  const properties = config['properties'] as readonly AstNode[] | undefined;
+  if (!properties) {
+    return null;
+  }
+  for (const prop of properties) {
+    if (propertyKeyName(prop) === propertyName) {
+      return prop;
+    }
+  }
+  return null;
+};
+
+/**
+ * Read a property key or member access identifier.
+ *
+ * Returns the identifier name for `Identifier` keys, or the underlying
+ * string literal value for computed access via `['name']` / `"name"`.
+ */
+export const getPropertyName = (node: unknown): string | null => {
+  if (typeof node !== 'object' || node === null) {
+    return null;
+  }
+
+  const { name } = node as { readonly name?: unknown };
+  if (typeof name === 'string') {
+    return name;
+  }
+
+  return isAstNode(node) ? extractStringLiteral(node) : null;
+};

package/src/locations.ts

@@ -0,0 +1,35 @@
+/** Shared source location helpers. */
+
+import type { SourceLocation } from './nodes.js';
+
+/** Find the byte offset's line number (1-based) in source code. */
+export const offsetToLine = (sourceCode: string, offset: number): number => {
+  let line = 1;
+  for (let i = 0; i < offset && i < sourceCode.length; i += 1) {
+    if (sourceCode[i] === '\n') {
+      line += 1;
+    }
+  }
+  return line;
+};
+
+/** Find the byte offset's line and column (1-based) in source code. */
+export const offsetToLineColumn = (
+  sourceCode: string,
+  offset: number
+): SourceLocation => {
+  let line = 1;
+  let column = 1;
+  const limit = Math.min(Math.max(offset, 0), sourceCode.length);
+
+  for (let i = 0; i < limit; i += 1) {
+    if (sourceCode[i] === '\n') {
+      line += 1;
+      column = 1;
+    } else {
+      column += 1;
+    }
+  }
+
+  return { column, line };
+};