@mertyalti/agentia-graph

Library for a version-2 Salesforce relationship graph: the document model, metadata extraction, canonical serialization, and secret redaction. It has no command-line interface.

Use it from another package. @mertyalti/agentia-docs is the documentation plugin that can commit a graph. @mertyalti/agentia-graph-cli is the plugin that inspects a working tree without committing. Human, agent, and CI callers use those plugins; they all call this library.

• @mertyalti/agentia-graph
• Install
• Quickstart
• Public API
• Document schema (v2)
• Extraction limitations
• Secret redaction and GraphError
• Consumers
• License

Install

Node.js >= 18. The package is ESM. The published entry is dist/index.js. Proprietary software: see LICENSE.md.

$ npm install @mertyalti/[email protected]

The @mertyalti scope resolves to the public npm registry by default.

Sibling checkout (local development)

{ "dependencies": { "@mertyalti/agentia-graph": "file:../agentia-graph" } }

$ npm run build

npm run build runs tsc and writes dist/. Link or path-install that dist/ into plugins before importing.

Quickstart

You pass the file list and a reader. This package does not run Git and does not choose built_at_commit.

import {
  extractSalesforceMetadata,
  writeGraphFile,
  parseGraphDocument,
} from '@mertyalti/agentia-graph'

const extracted = await extractSalesforceMetadata({
  paths, // repo-relative paths you already enumerated
  read: async (repoPath) => textOrUndefined,
})

writeGraphFile('graph.json', {
  version: 2,
  built_at_commit: full40HexSha, // caller-supplied
  extractor: 'salesforce-metadata',
  ...extracted,
})

const again = parseGraphDocument(JSON.parse(await readFile('graph.json', 'utf8')))

parseGraphDocument validates and returns the document in a stable order. renderGraphDocument redacts secrets and returns canonical JSON text. writeGraphFile writes that JSON by replacing a temp file in the same directory (replaceFileAtomically). If redaction still leaves a secret, it throws GraphError with code SECRET_DETECTED and does not write the file.

Public API

All of the following are imported from @mertyalti/agentia-graph (see src/index.ts / package exports):

| Export | Role | | --- | --- | | extractSalesforceMetadata, SalesforceExtractInput, EXTRACTION_LIMITATIONS | Walk classified Salesforce paths and return nodes, links, unresolved tokens, suggestions, and diagnostics. SalesforceExtractInput is { paths, read }. | | scanApex, ApexHit | Apex hits: constructor, label, soql, static, trigger. | | classifyMetadataPath, decodeMetadataName, IGNORED_METADATA_DIRECTORIES, MetadataHit | Metadata API path classification. ignored paths are omitted. An unrecognized path is undefined. | | METADATA_TYPES, RegistryType, RegistryChild | Metadata type registry used by the classifier. | | parseGraphDocument, renderGraphDocument, writeGraphFile | Validate, serialize, and store a graph document. | | GraphDocument, GraphNode, GraphFileNode, GraphComponentNode, GraphLink, GraphExtraction, GraphUnresolved, GraphSuggestion | Document types. | | redactText, redactValue, scanSecrets, scanStoredSecrets, SECRET_PATTERNS, SecretFinding | Secret scan and redaction. | | replaceFileAtomically | Temp file, then rename, in the destination directory. | | GraphError, GraphErrorCode, GRAPH_ERROR_CODES | Typed errors: CONFIGURATION_INVALID, SECRET_DETECTED. |

There is no deeper public subpath export contract beyond the package entry; consumers should import from @mertyalti/agentia-graph.

Document schema (v2)

• version is 2.
• extractor is salesforce-metadata.
• built_at_commit is 40 hex characters. The library does not invent it; the caller supplies it.
• A file node: kind: "file", id file:<path>.
• A component node: kind: "component", id sf:<metadata type>:<api name> (optionally with #… for a child).
• A link goes from a file to a component. relation is defines or references. certainty is structural. confidence is EXTRACTED and confidence_score is 1.
• unresolved records a token that has no component of the expected type in this repository. Some standard platform names are left unresolved on purpose (not a failed parse of a present file).
• suggestions are ambiguous tokens (for example an apex-static name that matches more than one component). A suggestion is not a link.
• Every written graph copies EXTRACTION_LIMITATIONS into the document.

Engineering notes on names left unresolved, and the rule that a later platform catalog must mark them platform, are in docs/unresolved-scope.md.

Extraction limitations

EXTRACTION_LIMITATIONS (copied into every written graph):

• Dynamic SOQL is not extracted.
• DML operands (insert, update, delete, undelete, merge, upsert) are not resolved.
• Nested SOQL relationship queries are not extracted.
• Apex declarations, generics, inheritance, and interfaces are not references.
• Static resources, documents, email templates, and content assets are omitted.
• Metadata types without a direct-reference rule are inventoried from the Metadata API type list and do not emit reference edges.

Inventory is separate from references: only a structural locator that resolves to one typed component becomes a reference. File bodies are not stored in the graph document.

Secret redaction and GraphError

Before a graph is rendered or written, string values are scanned and redacted (redactText / redactValue / scanSecrets / scanStoredSecrets). Patterns live in SECRET_PATTERNS.

| Code | When | | --- | --- | | CONFIGURATION_INVALID | Document fails schema or structural checks (for example bad node ids, link endpoints, or Zod validation). | | SECRET_DETECTED | A secret remains after redaction, or a stored secret is found in a path/body during extraction; the write is refused. |

GRAPH_ERROR_CODES is the const list of those codes. GraphError carries code and a redaction-safe message.

Consumers

| Package | Role | | --- | --- | | @mertyalti/agentia-docs | Documentation plugin: agentia docs graph / draft and related flows; can commit a graph on doc/<source revision>. | | @mertyalti/agentia-graph-cli | Host plugin: agentia graph generate / report / open / query / path; working-tree graph.json, not committed. |

Both depend on this library at 0.1.1 for publish and may use a file:../agentia-graph path dependency while developing next to this repo.

License

Copyright (c) mert yaltı. All rights reserved. See LICENSE.md. Permission is granted to install and use this software with Agentia Headless; redistribution, sublicensing, and modification require prior written permission. The software is designed to work with Copado's Agentia Headless; Copado Solutions is not the copyright holder of this package.