@chrisdudek/yg 4.2.0 → 5.0.0-alpha.1

package/dist/loader-hook-impl.d.ts

@@ -0,0 +1,9 @@
+declare function resolve(specifier: string, context: unknown, nextResolve: (specifier: string, context: unknown) => Promise<{
+    url: string;
+    shortCircuit?: boolean;
+}>): Promise<{
+    url: string;
+    shortCircuit?: boolean;
+}>;
+
+export { resolve };

package/dist/loader-hook-impl.js

@@ -0,0 +1,16 @@
+// src/ast/loader-hook-impl.ts
+import { pathToFileURL, fileURLToPath } from "url";
+import path from "path";
+var selfDir = path.dirname(fileURLToPath(import.meta.url));
+async function resolve(specifier, context, nextResolve) {
+  if (specifier.startsWith("@chrisdudek/yg/")) {
+    const exportName = specifier.slice("@chrisdudek/yg/".length);
+    const target = pathToFileURL(path.join(selfDir, `${exportName}.js`)).href;
+    return { url: target, shortCircuit: true };
+  }
+  return nextResolve(specifier, context);
+}
+export {
+  resolve
+};
+//# sourceMappingURL=loader-hook-impl.js.map

package/dist/structure.d.ts

@@ -0,0 +1,407 @@
+import { Tree } from 'web-tree-sitter';
+export { FindCommentsTarget, InFilePattern, closest, findComments, inFile, report, walk } from './ast.js';
+
+interface File {
+    /** repo-relative POSIX path */
+    path: string;
+    /** raw file content */
+    content: string;
+    /** parsed tree-sitter Tree, eagerly attached for files of a registered language; undefined otherwise. May carry parse errors (inspect ast.rootNode.hasError). */
+    ast?: unknown;
+    /** language id from the extension registry (e.g. 'typescript'); undefined for files with no registered grammar */
+    language?: string;
+}
+interface Port {
+    description: string;
+    /** aspect ids required of consumers */
+    aspects: string[];
+}
+type RelationType$1 = 'calls' | 'uses' | 'extends' | 'implements' | 'emits' | 'listens';
+interface Relation$1 {
+    type: RelationType$1;
+    /** target node path (e.g. 'orders/handler') */
+    target: string;
+    /** consumed port names (when applicable) */
+    consumes?: string[];
+}
+interface GraphNode$1 {
+    /** node path under model/ (e.g. 'cli/templates') */
+    id: string;
+    /** node_type id from yg-architecture.yaml */
+    type: string;
+    /** mapping entries from yg-node.yaml, untouched */
+    mapping: string[];
+    /** materialized files for this node's mapping (child carve-out applied for own node) */
+    files: File[];
+    ports: Record<string, Port>;
+}
+interface FsEntry {
+    /** basename, e.g. 'foo.ts' */
+    name: string;
+    kind: 'file' | 'dir';
+}
+interface Ctx {
+    node: GraphNode$1;
+    /** alias for node.files (own node files with child carve-out) */
+    files: File[];
+    fs: {
+        exists(path: string): 'file' | 'dir' | false;
+        list(dir: string): FsEntry[];
+        read(path: string): string;
+    };
+    graph: {
+        node(id: string): GraphNode$1 | undefined;
+        nodesByType(type: string): GraphNode$1[];
+        relationsFrom(node: GraphNode$1): Relation$1[];
+        relationsTo(node: GraphNode$1): Relation$1[];
+        children(node: GraphNode$1): GraphNode$1[];
+        flowParticipants(flowName: string): GraphNode$1[];
+    };
+    parseAst(file: File | string, language: string): unknown;
+    parseYaml(file: File | string): unknown;
+    parseJson(file: File | string): unknown;
+    parseToml(file: File | string): unknown;
+}
+interface Violation {
+    message: string;
+    file?: string;
+    line?: number;
+    column?: number;
+    /** Reserved prefix 'structure-aspect-*' for runtime emissions */
+    kind?: string;
+}
+/** check.mjs export signature (synchronous) */
+type CheckFunction = (ctx: Ctx) => Violation[];
+
+/**
+ * Applicability filter. Evaluated by the CLI against the graph before an aspect
+ * is considered effective on a node. If the predicate evaluates to false, the
+ * aspect is silently skipped on that node regardless of which channel attached it.
+ *
+ * Combines via AND with attach-site `when` declarations.
+ *
+ * Top-level atomic clauses are treated as implicit `all_of`.
+ */
+type WhenPredicate = BooleanClause | AtomicClause;
+type BooleanClause = {
+    all_of: WhenPredicate[];
+} | {
+    any_of: WhenPredicate[];
+} | {
+    not: WhenPredicate;
+};
+/**
+ * An atomic clause. All fields are optional — absent fields do not constrain.
+ * An empty object `{}` is therefore vacuously true. Parsers reject the empty
+ * form at the attach site (at least one operator/atomic key must be present).
+ */
+interface AtomicClause {
+    relations?: RelationClause;
+    descendants?: DescendantsClause;
+    node?: NodeClause;
+}
+type RelationClause = Partial<Record<RelationType, RelationMatch>>;
+interface RelationMatch {
+    target_type?: string;
+    /** Node path relative to model/ */
+    target?: string;
+    consumes_port?: string;
+}
+interface DescendantsClause {
+    relations?: RelationClause;
+    type?: string;
+    has_port?: string;
+}
+interface NodeClause {
+    type?: string;
+    has_port?: string;
+    has_mapping?: boolean;
+}
+
+/**
+ * FileWhenPredicate — per-file predicate for node_type classification.
+ *
+ * Two atoms: `path` (glob against file path) and `content` (regex against file content).
+ * Three operators: `all_of`, `any_of`, `not`.
+ * Top-level single atom permitted (implicit single-clause predicate).
+ *
+ * Distinct from aspect-level `WhenPredicate` (which uses graph-shape atoms
+ * relations/descendants/node). Same operator names, different atoms.
+ */
+type FileWhenPredicate = FileAtomicClause | FileBooleanClause;
+type FileAtomicClause = {
+    /** Glob pattern matched against the file's repo-relative path. */
+    path?: string;
+    /** Regex pattern matched against the file content. */
+    content?: string;
+};
+type FileBooleanClause = {
+    all_of: FileWhenPredicate[];
+} | {
+    any_of: FileWhenPredicate[];
+} | {
+    not: FileWhenPredicate;
+};
+
+interface IssueMessage {
+    /** What happened — facts, one line or short block */
+    what: string;
+    /** Why it's a problem — context for the agent */
+    why: string;
+    /** Concrete command or instruction to resolve */
+    next: string;
+}
+
+interface ReviewerConfig {
+    /** Tier name used when an aspect doesn't declare one explicitly */
+    default?: string;
+    /** At least one entry required; key is the tier name */
+    tiers: Record<string, LlmConfig>;
+}
+interface YggConfig {
+    version?: string;
+    quality?: QualityConfig;
+    /** Reviewer configuration — tiers + default. Optional in the type
+     *  to preserve FALLBACK_CONFIG ergonomics; validator emits
+     *  `config-reviewer-missing` when absent on a real project. */
+    reviewer?: ReviewerConfig;
+    parallel?: number;
+    debug?: boolean;
+}
+interface ArchitectureNodeType {
+    description: string;
+    aspects?: string[];
+    /** Per-aspect applicability filters for aspects listed in `aspects` */
+    aspectWhens?: Record<string, WhenPredicate>;
+    /** Per-aspect explicit status override for aspects listed in `aspects` (channel 3) */
+    aspectStatus?: Record<string, AspectStatus>;
+    parents?: string[];
+    relations?: Partial<Record<RelationType, string[]>>;
+    /**
+     * Whether nodes of this type require a log entry per source-file change.
+     * Undefined means caller should apply its own default (typically true).
+     */
+    log_required?: boolean;
+    /**
+     * Per-file classification predicate. Types without `when` are organizational
+     * (parent-only — nodes of that type cannot carry a non-empty `mapping:`).
+     */
+    when?: FileWhenPredicate;
+    /**
+     * When set to 'strict', backward enforcement applies: any repo file matching
+     * `when` must be in a node mapping of this type, and conversely a mapping
+     * file must satisfy `when`.
+     */
+    enforce?: 'strict';
+}
+interface ArchitectureDef {
+    node_types: Record<string, ArchitectureNodeType>;
+}
+interface QualityConfig {
+    max_direct_relations: number;
+    /** Per-node character budget. A node whose mapped source files plus the
+     *  reference files of its effective aspects exceed this total is an
+     *  `oversized-node` error. Default 40000. Binary files do not count; a node
+     *  may opt out via `sizeExempt`. */
+    max_node_chars?: number;
+}
+type RelationType = 'uses' | 'calls' | 'extends' | 'implements' | 'emits' | 'listens';
+/** Port on a target node — consumers must satisfy port's aspects */
+interface PortDef {
+    description: string;
+    aspects: string[];
+    /** Per-aspect applicability filters for aspects listed in `aspects` */
+    aspectWhens?: Record<string, WhenPredicate>;
+    /** Per-aspect explicit status override for aspects listed in `aspects` (channel 6) */
+    aspectStatus?: Record<string, AspectStatus>;
+}
+type ReviewerProvider = 'ollama' | 'openai' | 'anthropic' | 'google' | 'openai-compatible' | 'claude-code' | 'codex' | 'gemini-cli';
+/** LLM configuration — merged from yg-config.yaml + yg-secrets.yaml */
+interface LlmConfig {
+    provider: ReviewerProvider;
+    model: string;
+    endpoint?: string;
+    api_key?: string;
+    temperature: number;
+    consensus: number;
+    max_tokens: number | 'auto';
+    /** Ollama model_info key for context length (e.g. "qwen35.context_length"). Auto-detected if omitted. */
+    context_length_field?: string;
+    /** CLI providers: subprocess timeout in ms. Default: 120_000. */
+    timeout?: number;
+    /** Optional caps on reference files for aspects resolving to this tier. */
+    references?: {
+        /** Max bytes per single reference file. Default 65536 (64 KiB). */
+        max_bytes_per_file?: number;
+        /** Max sum of reference bytes per aspect. Default 262144 (256 KiB). */
+        max_total_bytes_per_aspect?: number;
+    };
+}
+interface NodeMeta {
+    name: string;
+    type: string;
+    description?: string;
+    aspects?: string[];
+    /** Per-aspect applicability filters for aspects listed in `aspects` */
+    aspectWhens?: Record<string, WhenPredicate>;
+    /** Per-aspect explicit status override for aspects listed in `aspects` (channel 1) */
+    aspectStatus?: Record<string, AspectStatus>;
+    ports?: Record<string, PortDef>;
+    relations?: Relation[];
+    /** Flat list of file/directory paths relative to repo root */
+    mapping?: string[];
+    /** Documented opt-out from the per-node character budget (`oversized-node`).
+     *  Use ONLY for nodes mapping an unsplittable generated or binary artifact
+     *  (lockfile, append-only changelog, image). Requires a justification. */
+    sizeExempt?: {
+        reason: string;
+    };
+}
+interface Relation {
+    target: string;
+    type: RelationType;
+    consumes?: string[];
+    /** For event relations (emits, listens): display name of the event, e.g. OrderPlaced */
+    event_name?: string;
+}
+interface GraphNode {
+    /** Path relative to model/, e.g. "orders/order-service" */
+    path: string;
+    /** Parsed yg-node.yaml content */
+    meta: NodeMeta;
+    /** Raw yg-node.yaml file content (for context assembly without disk access) */
+    nodeYamlRaw?: string;
+    /** Child nodes (subdirectories with yg-node.yaml) */
+    children: GraphNode[];
+    /** Parent node (null for top-level nodes) */
+    parent: GraphNode | null;
+}
+interface Artifact {
+    /** Filename, e.g. "content.md" */
+    filename: string;
+    /** Full text content of the file */
+    content: string;
+}
+interface AspectReviewerSpec {
+    type: 'llm' | 'deterministic';
+    /** Tier reference into ReviewerConfig.tiers; valid only when type === 'llm' */
+    tier?: string;
+}
+type AspectStatus = 'draft' | 'advisory' | 'enforced';
+/** Propagation modifier on implies edges. */
+type StatusInherit = 'strictest' | 'own-default';
+interface AspectDef {
+    name: string;
+    id: string;
+    description?: string;
+    /** Reviewer specification — type and optional tier reference */
+    reviewer: AspectReviewerSpec;
+    implies?: string[];
+    /** Per-implies applicability filters for aspect ids listed in `implies` */
+    impliesWhens?: Record<string, WhenPredicate>;
+    /** Per-implies status propagation modifier for aspect ids listed in `implies`.
+     *  Absent key → 'strictest' (default). */
+    impliesStatusInherit?: Record<string, StatusInherit>;
+    /** Global applicability filter for this aspect, applied on every channel */
+    when?: WhenPredicate;
+    artifacts: Artifact[];
+    /** Supporting files for the LLM reviewer (lookup tables, catalogues, contracts). Permitted only when reviewer.type === 'llm'. */
+    references?: Array<{
+        path: string;
+        description?: string;
+    }>;
+    /** Aspect-level default status. Absent → 'enforced'. Attach sites may override per the bump rule: bump up OK, downgrade is a validator error. */
+    status?: AspectStatus;
+}
+interface FlowDef {
+    /** Directory name under flows/, e.g. "checkout-flow" */
+    path: string;
+    name: string;
+    description?: string;
+    nodes: string[];
+    /** Optional aspect ids — aspects propagate to all participants */
+    aspects?: string[];
+    /** Per-aspect applicability filters for aspects listed in `aspects` */
+    aspectWhens?: Record<string, WhenPredicate>;
+    /** Per-aspect explicit status override for aspects listed in `aspects` (channel 5) */
+    aspectStatus?: Record<string, AspectStatus>;
+}
+interface SchemaDef {
+    /** Inferred from filename: 'node' | 'aspect' | 'flow' */
+    schemaType: string;
+}
+/**
+ * Architecture file load error.
+ *
+ * Bare string keeps backward compatibility with legacy parse failures.
+ * Structured form lets validators distinguish error codes — e.g.
+ * `when-predicate-invalid` vs. generic `architecture-invalid`.
+ */
+type ArchitectureLoadError = {
+    code: 'architecture-invalid';
+    messageData: IssueMessage;
+} | {
+    code: 'when-predicate-invalid';
+    messageData: IssueMessage;
+};
+interface Graph {
+    config: YggConfig;
+    architecture: ArchitectureDef;
+    /** Present when yg-architecture.yaml could not be parsed */
+    architectureError?: ArchitectureLoadError;
+    /** Present when yg-config.yaml could not be parsed and loader used fallback config */
+    configError?: string;
+    /** Structured form of configError — present when the config parse failure has what/why/next fields */
+    configErrorMessage?: IssueMessage;
+    /** Parse errors for yg-node.yaml files; reported as yaml-invalid */
+    nodeParseErrors?: Array<{
+        nodePath: string;
+        messageData: IssueMessage;
+    }>;
+    /** Parse errors for yg-aspect.yaml files. Each carries the structured
+     *  validator code for the validator to emit downstream. */
+    aspectParseErrors?: Array<{
+        aspectId: string;
+        code: string;
+        messageData: IssueMessage;
+    }>;
+    /** Structured error code carried alongside `configError`. Used by
+     *  validator to suppress dependent checks (e.g., skip aspect-tier-unknown
+     *  when the config is invalid). */
+    configErrorCode?: string;
+    /** All nodes indexed by their path (e.g. "orders/order-service") */
+    nodes: Map<string, GraphNode>;
+    aspects: AspectDef[];
+    flows: FlowDef[];
+    schemas: SchemaDef[];
+    /** Absolute path to the .yggdrasil/ directory */
+    rootPath: string;
+}
+
+/** Per-invocation parse cache shared by AST and structure runners. */
+type ParseCache = Map<string, {
+    content: string;
+    ast: Tree;
+}>;
+
+interface RunStructureAspectParams {
+    aspectDir: string;
+    aspectId: string;
+    nodePath: string;
+    graph: Graph;
+    projectRoot: string;
+    parseCache?: ParseCache;
+}
+interface RunStructureAspectResult {
+    violations: Violation[];
+    touchedFiles: string[];
+    succeeded?: boolean;
+}
+declare class StructureRunnerError extends Error {
+    readonly code: string;
+    readonly messageData: IssueMessage;
+    constructor(code: string, data: IssueMessage);
+}
+declare function runStructureAspect(params: RunStructureAspectParams): Promise<RunStructureAspectResult>;
+
+export { type CheckFunction, type Ctx, type File, type FsEntry, type GraphNode$1 as GraphNode, type Port, type Relation$1 as Relation, type RelationType$1 as RelationType, StructureRunnerError, type Violation, runStructureAspect };