guardlink 1.0.0 → 1.2.0

package/dist/agents/prompts.js

@@ -8,8 +8,8 @@ import { resolve } from 'node:path';
 /**
  * Build a prompt for annotation agents.
  *
- * Includes the GuardLink reference doc (truncated), current model summary,
- * user instructions, and precise GAL syntax rules with common pitfalls.
+ * Includes the GuardLink reference doc, current model summary with flows and exposures,
+ * flow-first threat modeling methodology, and precise GAL syntax rules.
  */
 export function buildAnnotatePrompt(userPrompt, root, model) {
     // Read the reference doc if available
@@ -18,8 +18,17 @@ export function buildAnnotatePrompt(userPrompt, root, model) {
     if (existsSync(refPath)) {
         refDoc = readFileSync(refPath, 'utf-8');
     }
-    let modelSummary = 'No threat model parsed yet. Run `guardlink parse` after annotating.';
+    // Fall back to docs/GUARDLINK_REFERENCE.md
+    if (!refDoc) {
+        const docsRefPath = resolve(root, 'docs', 'GUARDLINK_REFERENCE.md');
+        if (existsSync(docsRefPath)) {
+            refDoc = readFileSync(docsRefPath, 'utf-8');
+        }
+    }
+    let modelSummary = 'No threat model parsed yet. This may be a fresh project — define assets, threats, and controls first.';
     let existingIds = '';
+    let existingFlows = '';
+    let existingExposures = '';
     if (model) {
         const parts = [
             `${model.annotations_parsed} annotations`,
@@ -28,6 +37,8 @@ export function buildAnnotatePrompt(userPrompt, root, model) {
             `${model.threats.length} threats`,
             `${model.controls.length} controls`,
             `${model.mitigations.length} mitigations`,
+            `${model.flows.length} flows`,
+            `${model.boundaries.length} boundaries`,
         ];
         modelSummary = `Current model: ${parts.join(', ')}.`;
         // Include existing IDs so the agent doesn't create duplicates or dangling refs
@@ -36,45 +47,235 @@ export function buildAnnotatePrompt(userPrompt, root, model) {
         const controlIds = model.controls.filter(c => c.id).map(c => `#${c.id}`);
         if (threatIds.length + assetIds.length + controlIds.length > 0) {
             const sections = [];
-            if (threatIds.length)
-                sections.push(`Threats: ${threatIds.join(', ')}`);
             if (assetIds.length)
                 sections.push(`Assets: ${assetIds.join(', ')}`);
+            if (threatIds.length)
+                sections.push(`Threats: ${threatIds.join(', ')}`);
             if (controlIds.length)
                 sections.push(`Controls: ${controlIds.join(', ')}`);
-            existingIds = `\n\nExisting defined IDs (use these in @exposes, @mitigates, etc.):\n${sections.join('\n')}`;
+            existingIds = `\n\nExisting defined IDs (REUSE these — do NOT redefine):\n${sections.join('\n')}`;
+        }
+        // Include existing flows so agent understands the current flow graph
+        if (model.flows.length > 0) {
+            const flowLines = model.flows.slice(0, 30).map(f => `  ${f.source} -> ${f.target}${f.mechanism ? ` via ${f.mechanism}` : ''} (${f.location.file}:${f.location.line})`);
+            existingFlows = `\n\nExisting data flows (extend these, don't duplicate):\n${flowLines.join('\n')}`;
+            if (model.flows.length > 30)
+                existingFlows += `\n  ... and ${model.flows.length - 30} more`;
+        }
+        // Include unmitigated exposures so agent knows what still needs attention
+        // NOTE: Do NOT filter out @accepts — agents should see ALL exposures without real mitigations
+        const unmitigatedExposures = model.exposures.filter(e => {
+            return !model.mitigations.some(m => m.asset === e.asset && m.threat === e.threat);
+        });
+        if (unmitigatedExposures.length > 0) {
+            const expLines = unmitigatedExposures.slice(0, 20).map(e => `  ${e.asset} exposed to ${e.threat} [${e.severity || 'unrated'}] (${e.location.file}:${e.location.line})`);
+            existingExposures = `\n\nOpen exposures (no mitigation in code — add @mitigates if a control exists, or @audit to flag for human review):\n${expLines.join('\n')}`;
+            if (unmitigatedExposures.length > 20)
+                existingExposures += `\n  ... and ${unmitigatedExposures.length - 20} more`;
         }
     }
-    return `You are annotating a codebase with GuardLink security annotations.
+    return `You are an expert security engineer performing threat modeling as code.
+Your job is to read this codebase deeply, understand how code flows between components, and annotate it with GuardLink (GAL) security annotations that accurately represent the security posture.
 
-${refDoc ? '## GuardLink Reference\n\n' + refDoc.slice(0, 4000) + '\n\n' : ''}## Current State
-${modelSummary}${existingIds}
+This is NOT a vulnerability scanner. You are building a living threat model embedded in the code itself.
+Annotations capture what COULD go wrong, what controls exist, and how data moves — not just confirmed bugs.
 
-## Task
+${refDoc ? '## GuardLink Annotation Language Reference\n\n' + refDoc.slice(0, 4000) + '\n\n' : ''}## Current State
+${modelSummary}${existingIds}${existingFlows}${existingExposures}
+
+## Your Task
 ${userPrompt}
 
-## PRECISE Annotation Syntax (follow EXACTLY)
+## HOW TO THINK — Flow-First Threat Modeling
+
+Before writing ANY annotation, you MUST understand the code deeply:
+
+### Step 1: Map the Architecture
+Read ALL source files related to the area you're annotating. Trace:
+- Entry points (HTTP handlers, CLI commands, message consumers, event listeners)
+- Data paths (how user input flows through functions, classes, middleware, to storage or output)
+- Exit points (database writes, API calls, file I/O, rendered templates, responses)
+- Class hierarchies, inherited methods, shared utilities, middleware chains
+- Configuration and environment variable usage
+
+### Step 2: Identify Trust Boundaries
+Look for where trust changes:
+- External user → application code (HTTP boundary)
+- Application → database (data layer boundary)
+- Service → service (network boundary)
+- Frontend → backend (client/server boundary)
+- Application → third-party API (vendor boundary)
+- Internal code → spawned process (process boundary)
 
-Definitions go in .guardlink/definitions.js (or .py/.rs). Source files use only relationship verbs.
+### Step 3: Identify What Could Go Wrong
+At each boundary crossing and data transformation, ask:
+- What if this input is malicious? (@exposes)
+- What validation/sanitization exists? (@mitigates)
+- What sensitive data passes through here? (@handles)
+- Is there an assumption that could be violated? (@assumes)
+- Does this need human security review? (@audit)
+- Is this risk handled by someone else? (@transfers)
+
+### Step 4: Write Coupled Annotation Blocks
+NEVER write a single annotation in isolation. Every annotated location should tell a complete story.
+
+## ANNOTATION STYLE GUIDE — Write Like a Developer
+
+### Always Couple Annotations Together
+A file's doc-block should paint the full security picture of that module. Group annotations logically:
 
-### Definitions
 \`\`\`
-// @shield:begin -- "Example annotations for agent prompt, excluded from parsing"
-// @asset Server.Auth (#auth) -- "Authentication service"
-// @threat SQL_Injection (#sqli) [P0] cwe:CWE-89 -- "Unsanitized input in SQL"
-// @control Prepared_Statements (#prepared-stmts) -- "Parameterized queries"
+// @shield:begin -- "Example annotation block for reference, excluded from parsing"
+//
+// GOOD — Complete story at a single code location:
+// @exposes #auth-api to #sqli [P1] cwe:CWE-89 -- "User-supplied email passed to findUser() query builder"
+// @mitigates #auth-api against #sqli using #input-validation -- "Zod schema validates email format before query"
+// @flows User_Input -> #auth-api via POST./login -- "Login form submits credentials"
+// @flows #auth-api -> #user-db via TypeORM.findOne -- "Authenticated user lookup"
+// @handles pii on #auth-api -- "Processes email, password, session tokens"
+// @comment -- "Password comparison uses bcrypt.compare with timing-safe equality"
+//
+// BAD — Isolated annotation with no context:
+// @exposes #auth-api to #sqli -- "SQL injection possible"
+//
 // @shield:end
 \`\`\`
 
-### Relationships (use in source files)
+### Description Style — Reference Actual Code
+Descriptions must reference the real code: function names, variable names, libraries, mechanisms.
+
+\`\`\`
+// @shield:begin -- "Description examples, excluded from parsing"
+//
+// GOOD: -- "req.body.token passed to jwt.verify() without audience check"
+// GOOD: -- "bcrypt rounds set to 12 via BCRYPT_COST env var"
+// GOOD: -- "Rate limiter uses express-rate-limit at 100req/15min on /api/*"
+//
+// BAD:  -- "Input not validated"             (too vague — WHICH input? WHERE?)
+// BAD:  -- "Uses encryption"                 (WHAT encryption? On WHAT data?)
+// BAD:  -- "Security vulnerability exists"   (meaningless — be specific)
+//
+// @shield:end
+\`\`\`
+
+### @flows — Stitch the Complete Data Path
+@flows is the backbone of the threat model. Trace data movement accurately:
+
+\`\`\`
+// @shield:begin -- "Flow examples, excluded from parsing"
+//
+// Trace a request through the full stack:
+// @flows User_Browser -> #api-gateway via HTTPS -- "Client sends auth request"
+// @flows #api-gateway -> #auth-service via internal.gRPC -- "Gateway forwards to auth microservice"
+// @flows #auth-service -> #user-db via pg.query -- "Looks up user record by email"
+// @flows #auth-service -> #session-store via redis.set -- "Stores session token with TTL"
+// @flows #auth-service -> User_Browser via Set-Cookie -- "Returns session cookie to client"
+//
+// @shield:end
+\`\`\`
+
+### @boundary — Mark Every Trust Zone Crossing
+Place @boundary annotations where trust level changes between two components:
+
+\`\`\`
+// @shield:begin -- "Boundary examples, excluded from parsing"
+//
+// @boundary between #api-gateway and External_Internet (#public-boundary) -- "TLS termination, rate limiting at edge"
+// @boundary between #backend and #database (#data-boundary) -- "Application to persistence layer, connection pooling via pgBouncer"
+// @boundary between #app and #payment-provider (#vendor-boundary) -- "PCI-DSS scope boundary, tokenized card data only"
+//
+// @shield:end
+\`\`\`
+
+### Where to Place Annotations
+Annotations go in the file's top doc-block comment OR directly above the security-relevant code:
+
 \`\`\`
-// @shield:begin -- "Example annotations for agent prompt, excluded from parsing"
+// @shield:begin -- "Placement examples, excluded from parsing"
+//
+// FILE-LEVEL (top doc-block) — for module-wide security properties:
+// Place @exposes, @mitigates, @flows, @handles, @boundary that describe the module as a whole
+//
+// INLINE (above specific functions/methods) — for function-specific concerns:
+// Place @exposes, @mitigates above the exact function where the risk or control lives
+// Place @comment above tricky security-relevant code to explain intent
+//
+// @shield:end
+\`\`\`
+
+### Severity — Be Honest, Not Alarmist
+Annotations capture what COULD go wrong, calibrated to realistic risk:
+- **[P0] / [critical]**: Directly exploitable by external attacker, severe impact (RCE, auth bypass, data breach)
+- **[P1] / [high]**: Exploitable with some conditions, significant impact (privilege escalation, data leak)
+- **[P2] / [medium]**: Requires specific conditions or insider access (SSRF, info disclosure)
+- **[P3] / [low]**: Minor impact or very difficult to exploit (timing side-channels, verbose errors)
+
+Don't rate everything P0. A SQL injection in an admin-only internal tool is different from one in a public API.
+
+### @comment — Always Add Context
+Every annotation block should include at least one @comment explaining non-obvious security decisions, assumptions, or context that helps future developers (and AI tools) understand the "why".
+
+### @accepts — NEVER USE (Human-Only Decision)
+@accepts marks a risk as intentionally unmitigated. This is a **human-only governance decision** — it requires conscious risk ownership by a person or team.
+As an AI agent, you MUST NEVER write @accepts annotations. You cannot accept risk on behalf of humans.
+
+Instead, when you find an exposure with no mitigation in the code:
+1. Write the @exposes annotation to document the risk
+2. Add @audit to flag it for human security review
+3. Add @comment explaining what controls COULD be added
+4. Optionally add @assumes to document any assumptions the code makes
+
+Example — what to do when no mitigation exists:
+\`\`\`
+// @shield:begin -- "@accepts alternative examples, excluded from parsing"
+//
+// WRONG (AI rubber-stamping risk):
+// @accepts #prompt-injection on #ai-endpoint -- "Relying on model safety filters"
+//
+// RIGHT (flag for human review):
+// @exposes #ai-endpoint to #prompt-injection [P1] cwe:CWE-77 -- "User prompt passed directly to LLM API without sanitization"
+// @audit #ai-endpoint -- "No prompt sanitization — needs human review to decide: add input filter or accept risk"
+// @comment -- "Potential controls: #prompt-filter (input sanitization), #output-validator (response filtering)"
+//
+// @shield:end
+\`\`\`
+
+Leaving exposures unmitigated is HONEST. The dashboard and reports will surface them as open risks for humans to triage.
+
+### @shield — DO NOT USE Unless Explicitly Asked
+@shield and @shield:begin/@shield:end block AI coding assistants from reading the annotated code.
+This means any shielded code becomes invisible to AI tools — they cannot analyze, refactor, or annotate it.
+Do NOT add @shield annotations unless the user has EXPLICITLY requested it (e.g., "shield the crypto module").
+Adding @shield on your own initiative would actively harm the threat model by creating blind spots where AI cannot help.
+
+## PRECISE GAL Syntax
+
+Definitions go in .guardlink/definitions.{ts,js,py,rs}. Source files use only relationship verbs.
+
+### Definitions (in .guardlink/definitions file)
+\`\`\`
+// @shield:begin -- "Definition syntax examples, excluded from parsing"
+// @asset Server.Auth (#auth) -- "Authentication service handling login and session management"
+// @threat SQL_Injection (#sqli) [P0] cwe:CWE-89 -- "Unsanitized input reaches SQL query builder"
+// @control Prepared_Statements (#prepared-stmts) -- "Parameterized queries via ORM or driver placeholders"
+// @shield:end
+\`\`\`
+
+### Relationships (in source files)
+\`\`\`
+// @shield:begin -- "Relationship syntax examples, excluded from parsing"
 // @exposes #auth to #sqli [P0] cwe:CWE-89 owasp:A03:2021 -- "User input concatenated into query"
-// @mitigates #auth against #sqli using #prepared-stmts -- "Uses parameterized queries"
+// @mitigates #auth against #sqli using #prepared-stmts -- "Uses parameterized queries via sqlx"
+// @audit #auth -- "Timing attack risk — needs human review to decide if bcrypt constant-time comparison is sufficient"
+// @transfers #ddos from #api to #cdn -- "Cloudflare handles L7 DDoS mitigation"
 // @flows req.body.username -> db.query via string-concat -- "User input flows to SQL"
-// @boundary between #frontend and #api (#trust-boundary) -- "Public/private boundary"
-// @handles pii on #auth -- "Processes user credentials"
-// @comment -- "TODO: add rate limiting to prevent brute force"
+// @boundary between #frontend and #api (#web-boundary) -- "TLS-terminated public/private boundary"
+// @handles pii on #auth -- "Processes email, password, session tokens"
+// @validates #prepared-stmts for #auth -- "Integration test sqlInjectionTest.ts confirms parameterized queries block SQLi payloads"
+// @audit #auth -- "Session token rotation logic needs cryptographic review"
+// @assumes #auth -- "Upstream API gateway has already validated TLS and rate-limited requests"
+// @owns security-team for #auth -- "Security team reviews all auth PRs"
+// @comment -- "Password hashing uses bcrypt with cost factor 12, migration from SHA256 completed in v2.1"
 // @shield:end
 \`\`\`
 
@@ -84,13 +285,13 @@ Definitions go in .guardlink/definitions.js (or .py/.rs). Source files use only
    WRONG: \`@boundary api -- "desc"\`  (only one argument — will NOT parse)
    RIGHT: \`@boundary between #api and #client (#api-boundary) -- "Trust boundary"\`
 
-2. **@flows is ONE source → ONE target per line**: \`@flows <source> -> <target> via <mechanism>\`.
+2. **@flows is ONE source -> ONE target per line**: \`@flows <source> -> <target> via <mechanism>\`.
    WRONG: \`@flows A -> B, C -> D -- "desc"\`  (commas not supported)
    RIGHT: \`@flows A -> B via mechanism -- "desc"\` (one per line, repeat for multiple)
 
 3. **@exposes / @mitigates require DEFINED #id refs**: Every \`#id\` you reference must exist as a definition.
    Before using \`@exposes #app to #sqli\`, ensure \`@threat SQL_Injection (#sqli)\` exists in definitions.
-   Add new definitions to .guardlink/definitions.js FIRST, then reference them in source files.
+   Add new definitions to the .guardlink/definitions file FIRST, then reference them in source files.
 
 4. **Severity in square brackets**: \`[P0]\` \`[P1]\` \`[P2]\` \`[P3]\` or \`[critical]\` \`[high]\` \`[medium]\` \`[low]\`.
    Goes AFTER the threat ref in @exposes: \`@exposes #app to #sqli [P0] cwe:CWE-89\`
@@ -108,13 +309,32 @@ Definitions go in .guardlink/definitions.js (or .py/.rs). Source files use only
 
 8. **External refs are space-separated after severity**: \`cwe:CWE-89 owasp:A03:2021 capec:CAPEC-66\`
 
+9. **@comment always needs -- and quotes**: \`@comment -- "your note here"\`.
+   A bare \`@comment\` without description is valid but useless. Always include context.
+
+10. **One annotation per comment line.** Do NOT put two @verbs on the same line.
+
 ## Workflow
-1. Read existing definitions in .guardlink/definitions.js — reuse existing IDs
-2. Add any NEW threat/control definitions FIRST
-3. Then add relationship annotations (@exposes, @mitigates, @flows, etc.) in source files
-4. Use the project's comment style (// for JS/TS, # for Python, etc.)
-5. Run guardlink_validate (MCP) or \`guardlink validate\` to check for errors
-6. Fix any validation errors before finishing
+
+1. **Read first, annotate second.** Read ALL related source files before writing any annotation.
+   Trace the full call chain: entry point → middleware → handler → service → repository → database.
+   Understand class hierarchies, shared utilities, and configuration.
+
+2. **Read existing definitions** in the .guardlink/definitions file — reuse existing IDs, never duplicate.
+
+3. **Add NEW definitions FIRST** if you need new assets, threats, or controls.
+   Group related definitions together with section comments.
+
+4. **Annotate in coupled blocks.** For each security-relevant location, write the complete story:
+   @exposes + @mitigates (or @audit if no mitigation exists) + @flows + @comment at minimum.
+   Think: "what's the risk, what's the defense, how does data flow here, and what should the next developer know?"
+   NEVER write @accepts — that is a human-only governance decision. Use @audit to flag unmitigated risks for review.
+
+5. **Use the project's comment style** (// for JS/TS/Go/Rust, # for Python/Ruby/Shell, etc.)
+
+6. **Run validation** via guardlink_validate (MCP) or \`guardlink validate\` to check for errors.
+
+7. **Fix any validation errors** before finishing — especially dangling refs and malformed syntax.
 `;
 }
 //# sourceMappingURL=prompts.js.map

package/dist/agents/prompts.js.map

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

package/dist/analyze/index.d.ts

@@ -18,6 +18,8 @@ import { type AnalysisFramework } from './prompts.js';
 import { type LLMConfig } from './llm.js';
 export { type AnalysisFramework, FRAMEWORK_LABELS, FRAMEWORK_PROMPTS, buildUserMessage } from './prompts.js';
 export { type LLMConfig, type LLMProvider, buildConfig, autoDetectConfig } from './llm.js';
+export { GUARDLINK_TOOLS, createToolExecutor } from './tools.js';
+export type { ToolDefinition, ToolCall, ToolResult, ToolExecutor } from './llm.js';
 export interface ThreatReportOptions {
     root: string;
     model: ThreatModel;
@@ -26,6 +28,18 @@ export interface ThreatReportOptions {
     customPrompt?: string;
     stream?: boolean;
     onChunk?: (text: string) => void;
+    /** Max lines of context to include around each annotated line (default: 8) */
+    snippetContext?: number;
+    /** Max total characters for all code snippets combined (default: 40000) */
+    snippetBudget?: number;
+    /** Enable web search grounding (OpenAI Responses API) */
+    webSearch?: boolean;
+    /** Enable extended thinking (Anthropic) / reasoning (DeepSeek) */
+    extendedThinking?: boolean;
+    /** Token budget for thinking (default: 10000) */
+    thinkingBudget?: number;
+    /** Enable agentic tool use (CVE lookup, model validation, codebase search) */
+    enableTools?: boolean;
 }
 export interface ThreatReportResult {
     framework: AnalysisFramework;
@@ -36,10 +50,29 @@ export interface ThreatReportResult {
     savedTo?: string;
     inputTokens?: number;
     outputTokens?: number;
+    /** Thinking/reasoning content (if extended thinking was enabled) */
+    thinking?: string;
+    thinkingTokens?: number;
 }
+/**
+ * Collect project-level context for the LLM: language/framework, key
+ * dependencies, and deployment signals (Dockerfile, CI, etc.).
+ * Keeps output compact — targets ~2-4 KB.
+ */
+export declare function buildProjectContext(root: string): string;
+/**
+ * Extract source code snippets around annotated lines.
+ *
+ * For each annotation that has a file + line location, reads the
+ * surrounding `contextLines` lines from disk and returns a formatted
+ * block. Deduplicates overlapping ranges within the same file.
+ * Respects a total character budget to keep token usage bounded.
+ */
+export declare function extractCodeSnippets(root: string, model: ThreatModel, contextLines?: number, budgetChars?: number): string;
 /**
  * Serialize the threat model to a compact representation for LLM context.
- * Strips empty arrays and location details to save tokens.
+ * Includes file:line locations for all security-relevant annotations so
+ * the LLM can cross-reference with code snippets.
  */
 export declare function serializeModel(model: ThreatModel): string;
 /**

package/dist/analyze/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analyze/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,KAAK,iBAAiB,EAAyD,MAAM,cAAc,CAAC;AAC7G,OAAO,EAAE,KAAK,SAAS,EAA+B,MAAM,UAAU,CAAC;AAEvE,OAAO,EAAE,KAAK,iBAAiB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC7G,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAI3F,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,WAAW,CAAC;IACnB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,SAAS,EAAE,SAAS,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,iBAAiB,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAID;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAwEzD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAwEhE;AASD,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAwDjG;AAID,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA8BD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAenE;AAID,MAAM,WAAW,uBAAwB,SAAQ,iBAAiB;IAChE,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,GAAG,uBAAuB,EAAE,CAcrF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analyze/index.ts"],"names":[],"mappings":"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"}