@nac3/forge-cli 0.2.0-alpha.8 → 0.2.1-alpha.60

package/dist/qa/brain_matrix/types.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Brain matrix QA harness -- shared types.
+ *
+ * The harness runs a Scenario (a recipe: setup state + N turns +
+ * invariants) against N brains (provider+model pairs) and
+ * reports pass/fail per (scenario, brain) cell.
+ *
+ * Each Turn either:
+ *  - sends a `user_input` to the LLM and captures the response, or
+ *  - mocks a `tool_result` for a prior tool_use the LLM emitted
+ *    (multi-turn flows that would otherwise call real handlers).
+ *
+ * Invariants run AFTER the last turn, against the captured
+ * transcript. They are small, named, parameterised predicates.
+ *
+ * ASCII-only.
+ */
+import type { Nac3Verb } from '../../nac3/internal_manifest.js';
+export type BrainProvider = 'anthropic' | 'google_ai' | 'openai' | 'deepseek' | 'xai' | 'mistral' | 'cohere' | 'yujin_managed' | 'fake';
+export interface BrainConfig {
+    /** Stable id used in reports + filtering, e.g. "claude-sonnet-4-6". */
+    id: string;
+    provider: BrainProvider;
+    model: string;
+    tier: 'eco' | 'frontier';
+    /** Vault slot whose value is passed to the provider client.
+     *  When provider='fake', api_key is taken from `scripted` map
+     *  inline. */
+    vault_slot?: string;
+    /** Brain notes (e.g. "released 2026-04", "$0.10/1M in"). */
+    notes?: string;
+    /** Skip in default runs. Useful for slow or expensive brains. */
+    skip_default?: boolean;
+}
+/** Mocked workflow + graph state injected into the system prompt
+ *  for THIS scenario. The harness builds the prompt from these
+ *  fields plus the real static prompt + manifest stub. */
+export interface ScenarioSetup {
+    /** Optional workflow state -- injected as the "PROJECT WORKFLOW
+     *  STATE" section if present. Same shape as workflow/state.ts. */
+    workflow_state?: Record<string, unknown>;
+    /** Optional graph nodes injected as PROJECT KNOWLEDGE GRAPH. */
+    graph_nodes?: Array<{
+        kind: string;
+        slug: string;
+        description?: string;
+    }>;
+    /** Manifest mode for this scenario. Defaults to env / lazy. */
+    manifest_mode?: 'lazy' | 'eager';
+    /** Optional pre-history -- messages already exchanged before the
+     *  first scenario turn (sets up multi-turn context cheaply). */
+    pre_history?: Array<{
+        role: 'user' | 'assistant';
+        content: string;
+    }>;
+    /** alpha.59z.23 -- synthetic GLOBAL LEARNINGS to inject into the
+     *  system prompt for THIS scenario. The harness does not fetch
+     *  from the worker (that would couple QA to live D1 state); each
+     *  scenario that wants to validate respect-of-lesson behaviour
+     *  declares the lesson here. Mirrors the shape produced by
+     *  buildGlobalLearningsSection() in production. */
+    injected_global_learnings?: Array<{
+        slug: string;
+        rule_text: string;
+    }>;
+    /** alpha.59z.45 -- per-verb canned tool_result the harness returns
+     *  when the brain invokes that verb_id and no scenario.turn
+     *  tool_result is queued. Keyed by inner verb_id (e.g.
+     *  "yujin.manifest.read"). Without this, the harness returns
+     *  {ok:true, fake:true} which causes brains to confabulate. */
+    harness_responses?: Record<string, unknown>;
+    /** alpha.59z.45 -- ad-hoc text appended to the system prompt for
+     *  this scenario. Use when the scenario tests verbs not in the
+     *  default lazy stub (e.g. backend tools app.*, MCP bridge tools)
+     *  -- declares the verb stub directly so the brain knows it
+     *  exists + can invoke it. */
+    extra_system_prompt?: string;
+    /** alpha.59z.45 -- force MCP-meta verbs (yujin.mcp.*) into the
+     *  manifest stub. By default they are filtered (Invariant 1).
+     *  Scenarios that test MCP flows declare expose_mcp_verbs=true so
+     *  yujin.mcp.invoke-tool + yujin.mcp.list-bridges + ... appear in
+     *  the prompt and the brain can pick them. */
+    expose_mcp_verbs?: boolean;
+}
+/** One step in the scenario script. */
+export type ScenarioTurn = {
+    kind: 'user_says';
+    text: string;
+} | {
+    /** When the previous LLM response contained a tool_use, mock
+     *  the result so the LLM can continue. Match by tool name
+     *  or by index in the toolRounds[]. */
+    kind: 'tool_result';
+    tool_name?: string;
+    /** Mock the result payload. is_error defaults to false. */
+    result: unknown;
+    is_error?: boolean;
+};
+export type InvariantKind = 'tool_called' | 'tool_not_called' | 'no_invent_verb' | 'text_contains' | 'text_contains_any' | 'text_excludes' | 'max_turns' | 'verb_invoked' | 'verb_not_invoked' | 'args_match' | 'discover_schemas_before_invoke' | 'past_tense_only_after_invoke' | 'no_redundant_confirm' | 'regex_match' | 'regex_not_match' | 'args_contain_key' | 'min_tool_calls' | 'max_tool_calls' | 'min_text_length' | 'verb_invoked_in_order';
+export interface InvariantSpec {
+    /** Display name in reports. */
+    name: string;
+    kind: InvariantKind;
+    /** Parameters specific to the invariant kind. See invariants.ts
+     *  for shape per kind. */
+    params?: Record<string, unknown>;
+}
+export interface Scenario {
+    id: string;
+    description: string;
+    setup: ScenarioSetup;
+    turns: ScenarioTurn[];
+    invariants: InvariantSpec[];
+    /** Cost cap in tokens -- skip brain if estimated cost exceeds. */
+    max_tokens?: number;
+    /** Skip in default runs (e.g. exploratory scenarios). */
+    skip_default?: boolean;
+    /** alpha.59z.5 F3 -- override the runner's per-turn maxToolRounds
+     *  (default 3). Stateful scenarios where the LLM needs
+     *  tool_use -> result -> final reply benefit from 5+ (eco
+     *  brains spend one extra round per state lookup). */
+    max_tool_rounds?: number;
+}
+/** What the harness captures per (scenario, brain) execution. */
+export interface BrainTurnRecord {
+    /** Index in the response sequence. */
+    index: number;
+    /** Free-text from the LLM in this turn. */
+    text: string;
+    /** Tool calls the LLM emitted in this turn (name + args). */
+    tool_calls: Array<{
+        name: string;
+        args: Record<string, unknown>;
+    }>;
+    /** Token spend for this turn. */
+    tokens_in: number;
+    tokens_out: number;
+    /** Wall-clock ms. */
+    duration_ms: number;
+}
+export interface ScenarioRun {
+    scenario_id: string;
+    brain_id: string;
+    started_at: string;
+    ended_at: string;
+    turns: BrainTurnRecord[];
+    /** Total tokens + ms across all turns. */
+    total_tokens_in: number;
+    total_tokens_out: number;
+    total_ms: number;
+    /** Errors during the run (network, schema, etc) -- not
+     *  invariant failures. */
+    error?: string;
+}
+export interface InvariantResult {
+    invariant: string;
+    kind: InvariantKind;
+    pass: boolean;
+    reason: string;
+}
+export interface ScenarioReport {
+    run: ScenarioRun;
+    invariants: InvariantResult[];
+    /** True iff every invariant passed AND error is undefined. */
+    pass: boolean;
+}
+export interface MatrixReport {
+    generated_at: string;
+    forge_version: string;
+    scenarios: Array<{
+        id: string;
+        description: string;
+    }>;
+    brains: BrainConfig[];
+    /** Indexed by [scenario_id][brain_id]. */
+    results: Record<string, Record<string, ScenarioReport>>;
+}
+/** Re-export for fixture authors. */
+export type { Nac3Verb };
+//# sourceMappingURL=types.d.ts.map

package/dist/qa/brain_matrix/types.d.ts.map

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

package/dist/qa/brain_matrix/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/qa/brain_matrix/types.js.map

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

package/dist/qa/brain_matrix/validate_scenario.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Scenario shape validator. Catches common authoring mistakes
+ * BEFORE they show up as silent fake-gate failures:
+ *   - text_contains_any with `needles` instead of `substrs`
+ *   - text_excludes with `needle` instead of `substr`
+ *   - args_match without `verb_id` or `args`
+ *   - empty `turns[]`
+ *   - turns with neither `user_says` nor `tool_result`
+ *   - duplicate id within a scenario file (defensive)
+ *   - fake_responses count off from required turns
+ *
+ * Returns the list of human-readable warnings per scenario. Empty
+ * array = clean.
+ */
+import type { Scenario } from './types.js';
+export interface ValidationIssue {
+    scenario_id: string;
+    severity: 'error' | 'warning';
+    invariant: string | null;
+    message: string;
+}
+export declare function validateScenarioShape(s: Scenario): ValidationIssue[];
+//# sourceMappingURL=validate_scenario.d.ts.map

package/dist/qa/brain_matrix/validate_scenario.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate_scenario.d.ts","sourceRoot":"","sources":["../../../src/qa/brain_matrix/validate_scenario.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAiB,MAAM,YAAY,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAK,OAAO,GAAG,SAAS,CAAC;IACjC,SAAS,EAAI,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAM,MAAM,CAAC;CACrB;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,QAAQ,GAAG,eAAe,EAAE,CA2BpE"}

package/dist/qa/brain_matrix/validate_scenario.js

@@ -0,0 +1,128 @@
+export function validateScenarioShape(s) {
+    const out = [];
+    if (!s.id || typeof s.id !== 'string') {
+        out.push({ scenario_id: s.id ?? '<missing>', severity: 'error', invariant: null,
+            message: 'scenario.id is missing or not a string' });
+    }
+    if (!Array.isArray(s.turns) || s.turns.length === 0) {
+        out.push({ scenario_id: s.id, severity: 'error', invariant: null,
+            message: 'scenario.turns is empty' });
+    }
+    else {
+        for (let i = 0; i < s.turns.length; i++) {
+            const t = s.turns[i];
+            if (!t || (t.kind !== 'user_says' && t.kind !== 'tool_result')) {
+                out.push({ scenario_id: s.id, severity: 'error', invariant: null,
+                    message: 'turns[' + i + '].kind must be user_says or tool_result' });
+            }
+        }
+    }
+    if (!Array.isArray(s.invariants)) {
+        out.push({ scenario_id: s.id, severity: 'error', invariant: null,
+            message: 'scenario.invariants must be an array' });
+    }
+    else {
+        for (const inv of s.invariants) {
+            out.push(...validateInvariantShape(s.id, inv));
+        }
+    }
+    return out;
+}
+function validateInvariantShape(scenarioId, inv) {
+    const out = [];
+    if (!inv.name || typeof inv.name !== 'string') {
+        out.push({ scenario_id: scenarioId, severity: 'error', invariant: null,
+            message: 'invariant.name is missing' });
+        return out;
+    }
+    const p = (inv.params || {});
+    switch (inv.kind) {
+        case 'text_contains_any':
+            if (!Array.isArray(p.substrs)) {
+                const wrong = Array.isArray(p.needles) ? ' (found "needles", did you mean "substrs"?)' : '';
+                out.push({ scenario_id: scenarioId, severity: 'error', invariant: inv.name,
+                    message: 'text_contains_any requires params.substrs (string[])' + wrong });
+            }
+            break;
+        case 'text_contains':
+            if (typeof p.substr !== 'string') {
+                out.push({ scenario_id: scenarioId, severity: 'error', invariant: inv.name,
+                    message: 'text_contains requires params.substr (string)' });
+            }
+            break;
+        case 'text_excludes':
+            if (typeof p.substr !== 'string') {
+                const wrong = typeof p.needle === 'string' ? ' (found "needle", did you mean "substr"?)' : '';
+                out.push({ scenario_id: scenarioId, severity: 'error', invariant: inv.name,
+                    message: 'text_excludes requires params.substr (string)' + wrong });
+            }
+            break;
+        case 'verb_invoked':
+        case 'verb_not_invoked':
+        case 'tool_called':
+        case 'tool_not_called':
+        case 'no_invent_verb':
+            if (inv.kind === 'verb_invoked' || inv.kind === 'verb_not_invoked') {
+                if (typeof p.verb_id !== 'string') {
+                    out.push({ scenario_id: scenarioId, severity: 'error', invariant: inv.name,
+                        message: inv.kind + ' requires params.verb_id (string)' });
+                }
+            }
+            break;
+        case 'args_match':
+            if (typeof p.verb_id !== 'string' || typeof p.args !== 'object') {
+                out.push({ scenario_id: scenarioId, severity: 'error', invariant: inv.name,
+                    message: 'args_match requires params.verb_id (string) and params.args (object)' });
+            }
+            break;
+        case 'discover_schemas_before_invoke':
+            if (typeof p.verb_id !== 'string') {
+                out.push({ scenario_id: scenarioId, severity: 'error', invariant: inv.name,
+                    message: 'discover_schemas_before_invoke requires params.verb_id (string)' });
+            }
+            break;
+        case 'max_turns':
+        case 'min_text_length':
+        case 'min_tool_calls':
+        case 'max_tool_calls':
+            if (typeof (p.max ?? p.min) !== 'number') {
+                out.push({ scenario_id: scenarioId, severity: 'warning', invariant: inv.name,
+                    message: inv.kind + ' typically needs params.max or params.min (number)' });
+            }
+            break;
+        case 'regex_match':
+        case 'regex_not_match':
+            if (typeof p.pattern !== 'string') {
+                out.push({ scenario_id: scenarioId, severity: 'error', invariant: inv.name,
+                    message: inv.kind + ' requires params.pattern (string)' });
+            }
+            else {
+                try {
+                    new RegExp(p.pattern, p.flags || '');
+                }
+                catch (e) {
+                    out.push({ scenario_id: scenarioId, severity: 'error', invariant: inv.name,
+                        message: inv.kind + ' has invalid regex: ' + (e instanceof Error ? e.message : String(e)) });
+                }
+            }
+            break;
+        case 'args_contain_key':
+            if (typeof p.verb_id !== 'string' || typeof p.key !== 'string') {
+                out.push({ scenario_id: scenarioId, severity: 'error', invariant: inv.name,
+                    message: 'args_contain_key requires params.verb_id + params.key (both strings)' });
+            }
+            break;
+        case 'verb_invoked_in_order':
+            if (!Array.isArray(p.sequence) || p.sequence.length < 2) {
+                out.push({ scenario_id: scenarioId, severity: 'error', invariant: inv.name,
+                    message: 'verb_invoked_in_order requires params.sequence (string[], length >= 2)' });
+            }
+            break;
+        /* no-param invariants -- nothing to check */
+        case 'past_tense_only_after_invoke':
+        case 'no_redundant_confirm':
+            break;
+    }
+    return out;
+}
+//# sourceMappingURL=validate_scenario.js.map

package/dist/qa/brain_matrix/validate_scenario.js.map

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

package/dist/semantic_graph/ast_extract.d.ts

@@ -0,0 +1,15 @@
+export type ExportKind = 'function' | 'const' | 'class' | 'type' | 'interface';
+export interface AstExport {
+    name: string;
+    kind: ExportKind;
+    /** True when the export is PascalCase AND returns / yields JSX. */
+    is_component: boolean;
+    /** True for `function useFoo()` or `const useFoo = ...`. */
+    is_hook: boolean;
+    /** First leading JSDoc paragraph, trimmed to 200 chars. '' when
+     *  none was present. */
+    jsdoc: string;
+}
+/** Parse a TS/TSX/JS/JSX source + return its top-level exports. */
+export declare function extractExportsAst(source: string, fileName?: string): AstExport[];
+//# sourceMappingURL=ast_extract.d.ts.map

package/dist/semantic_graph/ast_extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast_extract.d.ts","sourceRoot":"","sources":["../../src/semantic_graph/ast_extract.ts"],"names":[],"mappings":"AAqBA,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,WAAW,CAAC;AAE/E,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,mEAAmE;IACnE,YAAY,EAAE,OAAO,CAAC;IACtB,4DAA4D;IAC5D,OAAO,EAAE,OAAO,CAAC;IACjB;4BACwB;IACxB,KAAK,EAAE,MAAM,CAAC;CACf;AAID,mEAAmE;AACnE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,SAAW,GAAG,SAAS,EAAE,CAqElF"}

package/dist/semantic_graph/ast_extract.js

@@ -0,0 +1,162 @@
+/**
+ * PND-020 Phase 2a -- AST-based export extractor.
+ *
+ * Replaces the regex pass in graph_component_watcher with a real
+ * TypeScript Compiler API walk. Gains over the regex:
+ *   1. Robust to comments / strings that contain the word "export".
+ *   2. Detects JSX content for a tighter component classification
+ *      (PascalCase + actually returns JSX/TSX = 'component', else
+ *      'module' even when the path includes /components/).
+ *   3. Pulls the leading JSDoc as a `purpose` hint when present.
+ *   4. Captures hook-like exports (function name starts with `use`
+ *      + at least one `useX` call body) to enrich `solves`.
+ *
+ * The spec originally called for @typescript-eslint/parser; we use
+ * the bundled `typescript` compiler API instead so we don't add a
+ * runtime dep just for this. The output shape is identical.
+ *
+ * ASCII-only.
+ */
+import * as ts from 'typescript';
+const MAX_EXPORTS_PER_FILE = 10;
+/** Parse a TS/TSX/JS/JSX source + return its top-level exports. */
+export function extractExportsAst(source, fileName = 'in.tsx') {
+    if (!source)
+        return [];
+    const sf = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, /* setParentNodes */ true, fileName.endsWith('.tsx') || fileName.endsWith('.jsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS);
+    const out = [];
+    const seen = new Set();
+    function push(e) {
+        if (seen.has(e.name))
+            return;
+        seen.add(e.name);
+        out.push(e);
+    }
+    for (const stmt of sf.statements) {
+        if (out.length >= MAX_EXPORTS_PER_FILE)
+            break;
+        const mods = ts.canHaveModifiers(stmt) ? ts.getModifiers(stmt) ?? [] : [];
+        const isExported = mods.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+        const isDefault = mods.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword);
+        if (!isExported)
+            continue;
+        if (ts.isFunctionDeclaration(stmt) && stmt.name) {
+            const name = stmt.name.text;
+            const returnsJsx = bodyReturnsJsx(stmt.body);
+            const usesHook = bodyCallsHook(stmt.body);
+            push({
+                name,
+                kind: 'function',
+                is_component: /^[A-Z]/.test(name) && returnsJsx,
+                is_hook: name.startsWith('use') && /^use[A-Z]/.test(name) && usesHook,
+                jsdoc: jsdocOf(stmt, sf),
+            });
+        }
+        else if (ts.isClassDeclaration(stmt) && stmt.name) {
+            push({
+                name: stmt.name.text,
+                kind: 'class',
+                is_component: false,
+                is_hook: false,
+                jsdoc: jsdocOf(stmt, sf),
+            });
+        }
+        else if (ts.isVariableStatement(stmt)) {
+            /* `export const Foo = ...` -- may bind multiple names. */
+            for (const decl of stmt.declarationList.declarations) {
+                if (!ts.isIdentifier(decl.name))
+                    continue;
+                const name = decl.name.text;
+                const init = decl.initializer;
+                let returnsJsx = false, usesHook = false;
+                if (init && (ts.isArrowFunction(init) || ts.isFunctionExpression(init))) {
+                    returnsJsx = bodyReturnsJsx(init.body);
+                    usesHook = bodyCallsHook(init.body);
+                }
+                push({
+                    name,
+                    kind: 'const',
+                    is_component: /^[A-Z]/.test(name) && returnsJsx,
+                    is_hook: name.startsWith('use') && /^use[A-Z]/.test(name) && usesHook,
+                    jsdoc: jsdocOf(stmt, sf),
+                });
+                if (out.length >= MAX_EXPORTS_PER_FILE)
+                    break;
+            }
+        }
+        else if (ts.isTypeAliasDeclaration(stmt)) {
+            push({ name: stmt.name.text, kind: 'type', is_component: false, is_hook: false, jsdoc: jsdocOf(stmt, sf) });
+        }
+        else if (ts.isInterfaceDeclaration(stmt)) {
+            push({ name: stmt.name.text, kind: 'interface', is_component: false, is_hook: false, jsdoc: jsdocOf(stmt, sf) });
+        }
+        else if (isDefault && ts.isExportAssignment(stmt) && ts.isIdentifier(stmt.expression)) {
+            push({ name: stmt.expression.text, kind: 'const', is_component: false, is_hook: false, jsdoc: jsdocOf(stmt, sf) });
+        }
+    }
+    return out;
+}
+function bodyReturnsJsx(body) {
+    if (!body)
+        return false;
+    let found = false;
+    function visit(n) {
+        if (found)
+            return;
+        if (ts.isJsxElement(n) || ts.isJsxSelfClosingElement(n) || ts.isJsxFragment(n)) {
+            found = true;
+            return;
+        }
+        n.forEachChild(visit);
+    }
+    visit(body);
+    return found;
+}
+function bodyCallsHook(body) {
+    if (!body)
+        return false;
+    let found = false;
+    function visit(n) {
+        if (found)
+            return;
+        if (ts.isCallExpression(n)) {
+            const ex = n.expression;
+            const name = ts.isIdentifier(ex) ? ex.text
+                : ts.isPropertyAccessExpression(ex) && ts.isIdentifier(ex.name) ? ex.name.text
+                    : '';
+            if (/^use[A-Z]/.test(name)) {
+                found = true;
+                return;
+            }
+        }
+        n.forEachChild(visit);
+    }
+    visit(body);
+    return found;
+}
+function jsdocOf(node, sf) {
+    const fullText = sf.getFullText();
+    const ranges = ts.getLeadingCommentRanges(fullText, node.getFullStart());
+    if (!ranges || ranges.length === 0)
+        return '';
+    /* Take the last JSDoc block before the node (closest). */
+    for (let i = ranges.length - 1; i >= 0; i--) {
+        const r = ranges[i];
+        if (r.kind !== ts.SyntaxKind.MultiLineCommentTrivia)
+            continue;
+        const raw = fullText.slice(r.pos, r.end);
+        if (!raw.startsWith('/**'))
+            continue;
+        const stripped = raw
+            .replace(/^\/\*\*+/, '')
+            .replace(/\*+\/$/, '')
+            .split(/\r?\n/)
+            .map((ln) => ln.replace(/^\s*\*\s?/, '').trim())
+            .filter((ln) => ln && !ln.startsWith('@'))
+            .join(' ')
+            .trim();
+        return stripped.slice(0, 200);
+    }
+    return '';
+}
+//# sourceMappingURL=ast_extract.js.map

package/dist/semantic_graph/ast_extract.js.map

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

package/dist/semantic_graph/derive.d.ts

@@ -0,0 +1,36 @@
+import type { GraphNode, GraphEdge } from './types.js';
+/** Extrae los specifiers de import reales de un archivo TS/JS.
+ *  Solo statements de import/export-from/dynamic-import; la comilla
+ *  va inmediatamente tras `from`/`import`/`import(`. */
+export declare function extractImportSpecifiers(source: string): string[];
+export interface DerivedGraph {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    stats: {
+        module_nodes: number;
+        lib_nodes: number;
+        module_edges: number;
+        lib_edges: number;
+        skipped_dangling: number;
+    };
+}
+/** Deriva nodos (modulo + libreria) + aristas validadas del
+ *  proyecto. No toca el store; el caller persiste. */
+export declare function deriveProjectGraph(opts: {
+    project_root: string;
+    project_slug: string;
+    enrich?: boolean;
+    fetchImpl?: typeof fetch;
+}): Promise<DerivedGraph>;
+/** GRAPH-1 -- deriva + PERSISTE el grafo (upsert nodos + aristas +
+ *  poda colgantes). Idempotente. Lo llaman el endpoint del boton
+ *  Refresh y el auto-regen del component-watcher. */
+export declare function regenerateAndPersist(opts: {
+    project_root: string;
+    project_slug: string;
+    enrich?: boolean;
+    fetchImpl?: typeof fetch;
+}): Promise<DerivedGraph['stats'] & {
+    pruned: number;
+}>;
+//# sourceMappingURL=derive.d.ts.map

package/dist/semantic_graph/derive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../../src/semantic_graph/derive.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA4CvD;;wDAEwD;AACxD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAchE;AAgBD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAA;KAAE,CAAC;CACvH;AAqCD;sDACsD;AACtD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,GAAG,OAAO,CAAC,YAAY,CAAC,CAuFxB;AAED;;qDAEqD;AACrD,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,GAAG,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAMtD"}