structured-context 0.10.0 → 0.11.0

package/dist/render/render.js

@@ -1,7 +1,7 @@
-import { filterNodes } from '../filter/filter-nodes';
+import { shortenPluginName } from '@/plugins/util';
+import { updateSpaceField } from '../config';
+import { assembleSpaceGraph } from '../load-space-graph';
 import { loadPlugins } from '../plugins/loader';
-import { readSpace } from '../read/read-space';
-import { buildSpaceGraph } from '../space-graph';
 import { buildFormatRegistry } from './registry';
 export async function executeRender(formatName, context, options) {
     const pluginMap = context.space?.plugins ?? {};
@@ -12,17 +12,21 @@ export async function executeRender(formatName, context, options) {
         const available = registry.map((r) => r.qualifiedName).join(', ');
         throw new Error(`Unknown render format: "${formatName}".${available ? ` Available: ${available}` : ' No formats registered.'}`);
     }
-    const { nodes: allNodes } = await readSpace(context);
-    // Validate: drop nodes that fail schema validation
-    const { schemaValidator } = context;
-    const validNodes = allNodes.filter((node) => schemaValidator(node.schemaData));
-    const levels = context.schema.metadata.hierarchy?.levels ?? [];
-    let graph = buildSpaceGraph(validNodes, levels);
-    // Filter: apply filter expression if provided
-    if (options.filter) {
-        const expression = context.space.views?.[options.filter]?.expression ?? options.filter;
-        graph = await filterNodes(expression, graph);
-    }
-    const pluginContext = { ...context, pluginConfig: entry.plugin.pluginConfig };
-    return entry.plugin.plugin.render.render(pluginContext, graph, { format: entry.format.name });
+    const graph = await assembleSpaceGraph(context, { filter: options.filter });
+    const shortName = shortenPluginName(entry.plugin.plugin.name);
+    const pluginContext = {
+        ...context,
+        pluginConfig: entry.plugin.pluginConfig,
+        callbacks: {
+            persistConfig: (updates) => {
+                for (const [field, value] of Object.entries(updates)) {
+                    updateSpaceField(context.space.name, field, value, shortName);
+                }
+            },
+        },
+    };
+    return entry.plugin.plugin.render.render(pluginContext, graph, {
+        format: entry.format.name,
+        data: options.data,
+    });
 }

package/dist/schema/evaluate-rule.js

@@ -52,6 +52,7 @@ function flattenNode(node) {
         resolvedType: node.resolvedType,
         resolvedParentTitle: node.resolvedParents[0]?.title, // first parent or undefined, provided for convenience
         resolvedParentTitles: node.resolvedParents.map((r) => r.title), // full array of parent titles
+        resolvedLinks: node.resolvedLinks,
     };
 }
 /**

package/dist/schema/schema.d.ts

@@ -1,6 +1,8 @@
 import { type AnySchemaObject, type ValidateFunction } from 'ajv';
 import type { SchemaMetadata, SchemaWithMetadata } from '../types';
-export declare const bundledSchemasDir: string;
+export declare let bundledSchemasDir: string;
+/** Override the bundled schemas directory (e.g. when running in a bundled context). */
+export declare function setBundledSchemasDir(dir: string): void;
 export declare function readRawSchema(schemaPath: string): AnySchemaObject;
 /**
  * Build the full two-layer registry for a schema path:

package/dist/schema/schema.js

@@ -6,8 +6,12 @@ import Ajv, {} from 'ajv';
 import JSON5 from 'json5';
 import { DIALECT_META_SCHEMA, METADATA_SCHEMA, SCHEMA_META_ID, } from './metadata-contract';
 import { isObject, mergeVariantProperties, resolveJsonPointer } from './schema-refs';
-const packageDir = dirname(fileURLToPath(import.meta.url));
-export const bundledSchemasDir = join(packageDir, '..', '..', 'schemas');
+const packageDir = import.meta.url ? dirname(fileURLToPath(import.meta.url)) : '';
+export let bundledSchemasDir = packageDir ? join(packageDir, '..', '..', 'schemas') : '';
+/** Override the bundled schemas directory (e.g. when running in a bundled context). */
+export function setBundledSchemasDir(dir) {
+    bundledSchemasDir = dir;
+}
 const validateMetadataContract = new Ajv().compile(METADATA_SCHEMA);
 export function readRawSchema(schemaPath) {
     return JSON5.parse(readFileSync(resolve(schemaPath), 'utf-8'));

package/dist/schemas/_knowledge_wiki.json

@@ -207,7 +207,7 @@
     },
     "note": {
       "type": "object",
-      "description": "Personal notes, journal entries, appointments, experiential records. Your own data about your journey — not sourced from external material.",
+      "description": "Personal notes, journal entries, talk notes, or rough thoughts not drawn from an external URL.",
       "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
       "properties": {
         "type": { "const": "note" },

package/dist/space-context.d.ts

@@ -0,0 +1,24 @@
+import { type Config } from './config';
+import type { SpaceContext } from './types';
+/** Thrown by createSpaceContext when no space matches the given name. */
+export declare class SpaceNotFoundError extends Error {
+    readonly spaceName: string;
+    constructor(spaceName: string);
+}
+export interface CreateSpaceContextOptions {
+    /**
+     * Directory to anchor relative plugin-config paths against. Defaults to the source
+     * directory recorded by loadConfig (space.sourceDir). Required for a hand-assembled
+     * Config, which has no source file — pass e.g. process.cwd(), or the directory the
+     * paths are relative to.
+     */
+    configDir?: string;
+}
+/**
+ * Build a SpaceContext for a named space from an already-loaded config.
+ *
+ * Library-safe: throws {@link SpaceNotFoundError} on an unknown space rather than
+ * writing to the console or exiting the process. CLI callers that want the
+ * exit-on-error behaviour should wrap this (see buildSpaceContext in index.ts).
+ */
+export declare function createSpaceContext(spaceName: string, config: Config, options?: CreateSpaceContextOptions): SpaceContext;

package/dist/space-context.js

@@ -0,0 +1,41 @@
+import { resolveSchema } from './config';
+import { loadSchema } from './schema/schema';
+/** Thrown by createSpaceContext when no space matches the given name. */
+export class SpaceNotFoundError extends Error {
+    spaceName;
+    constructor(spaceName) {
+        super(`Unknown space "${spaceName}"`);
+        this.spaceName = spaceName;
+        this.name = 'SpaceNotFoundError';
+    }
+}
+/**
+ * Build a SpaceContext for a named space from an already-loaded config.
+ *
+ * Library-safe: throws {@link SpaceNotFoundError} on an unknown space rather than
+ * writing to the console or exiting the process. CLI callers that want the
+ * exit-on-error behaviour should wrap this (see buildSpaceContext in index.ts).
+ */
+export function createSpaceContext(spaceName, config, options = {}) {
+    const space = config.spaces.find((s) => s.name === spaceName);
+    if (!space) {
+        throw new SpaceNotFoundError(spaceName);
+    }
+    const configDir = options.configDir ?? space.sourceDir;
+    if (configDir === undefined) {
+        throw new Error(`Cannot resolve a config directory for space "${spaceName}": its Config was not loaded from a ` +
+            `file. Pass options.configDir (e.g. process.cwd()) to anchor relative plugin paths, or load ` +
+            `the config with loadConfig().`);
+    }
+    const resolvedSchemaPath = resolveSchema(config, space);
+    const { schema, schemaRefRegistry, schemaValidator } = loadSchema(resolvedSchemaPath);
+    return {
+        space,
+        config,
+        resolvedSchemaPath,
+        schema,
+        schemaRefRegistry,
+        schemaValidator,
+        configDir,
+    };
+}

package/dist/types.d.ts

@@ -56,6 +56,42 @@ export type UnresolvedRef = {
     /** Human-readable message matching validate-graph output format. */
     message: string;
 };
+/**
+ * Shared fields for all content link variants.
+ */
+type ContentLinkBase = {
+    /** Display text of the link (text content for markdown links, inner text or target for wikilinks). */
+    text: string;
+    /** Raw link target: URL for markdown links, wikilink path (without [[ ]]) for wikilinks. */
+    target: string;
+    /** Whether the link navigates to a resource or transcludes/embeds it. */
+    action: 'link' | 'embed';
+    /** Anchor fragment (heading or block ref, e.g. 'heading-title' or '^blockid') if present. */
+    anchor?: string;
+};
+/**
+ * A link extracted from node content at parse time, before location classification.
+ * Populated by plugins that support content link extraction (e.g. the markdown plugin).
+ */
+export type ContentLink = ContentLinkBase & {
+    /** Link syntax — used during resolution to determine how to classify the target. */
+    linkSyntax: 'wikilink' | 'markdown';
+};
+/**
+ * A fully classified link from node content, after location resolution.
+ * Present on SpaceNode after graph resolution.
+ */
+export type ResolvedContentLink = ContentLinkBase & {
+    /**
+     * Resolved location classification:
+     * - 'node'     — wikilink resolved to a known space node
+     * - 'internal' — wikilink or relative path, in the source system but not a space node
+     * - 'external' — http/https URL
+     * - 'system'   — file:// URL
+     * - 'protocol' — other scheme (e.g. obsidian://)
+     */
+    location: 'node' | 'internal' | 'external' | 'system' | 'protocol';
+};
 /**
  * A node as produced by a parse plugin — raw type from content, no graph resolution applied.
  * Core enriches this into a SpaceNode after parsing.
@@ -71,6 +107,11 @@ export type BaseNode = {
     linkTargets: string[];
     /** Raw type string from content, as written by the user. */
     type: string;
+    /**
+     * Links extracted from content body and non-edge string fields at parse time.
+     * Populated by plugins that support content link extraction; absent if not populated.
+     */
+    contentLinks?: ContentLink[];
 };
 /**
  * A fully resolved node — enriched by core after plugin parsing.
@@ -85,6 +126,11 @@ export type SpaceNode = BaseNode & {
      * Always present, empty if no parents resolved.
      */
     resolvedParents: ResolvedParentRef[];
+    /**
+     * Links from content body and non-edge fields, with location classified after graph resolution.
+     * Always present, empty if the plugin did not populate rawContentLinks.
+     */
+    resolvedLinks: ResolvedContentLink[];
 };
 export type ParseIssue = {
     /** Source identifier of the file or item (filename or heading title). */
@@ -165,6 +211,12 @@ export interface FileValidationResult {
         message: string;
     }>;
     errorCount: number;
+    /** Warnings keyed by composite id. Do not affect exit code or errorCount. */
+    warnings: Record<string, {
+        kind: string;
+        message: string;
+    }>;
+    warningCount: number;
     inSpace: true;
 }
 export interface FileNotInSpaceResult {

package/dist/validate.d.ts

@@ -1,7 +1,7 @@
 import type { ErrorObject } from 'ajv';
 import type { Config } from './config';
 import { extractEntityInfo } from './schema/schema';
-import type { GraphViolation, ParseIssue, RuleViolation, SchemaWithMetadata, SpaceContext, SpaceNode, ValidateFileOutput } from './types';
+import type { GraphViolation, ParseIssue, ReadSpaceResult, RuleViolation, SchemaWithMetadata, SpaceContext, SpaceNode, ValidateFileOutput } from './types';
 export interface FormattedError {
     message: string;
     dedupeKey: string;
@@ -27,6 +27,11 @@ export interface ValidationResult {
     hierarchyViolations: GraphViolation[];
     orphans: SpaceNode[];
     parseIssues: ParseIssue[];
+    /** Content links that could not be resolved to a space node. Warning only — not counted in errors. */
+    unresolvedContentLinks: Array<{
+        file: string;
+        target: string;
+    }>;
 }
 /**
  * Format AJV errors for better readability.
@@ -37,7 +42,9 @@ export declare function formatErrors(errors: ErrorObject[], schema: SchemaWithMe
  * Run full validation on a space and return a structured result.
  * Does not output to console or call process.exit.
  */
-export declare function validateSpace(context: SpaceContext): Promise<ValidationResult>;
+export declare function validateSpace(context: SpaceContext, options?: {
+    readResult?: ReadSpaceResult;
+}): Promise<ValidationResult>;
 /**
  * Validate a single file within its space.
  *
@@ -47,4 +54,6 @@ export declare function validateSpace(context: SpaceContext): Promise<Validation
  * Returns a result object — does not output to console or call process.exit.
  * If the file is not in any configured space, returns a result with `inSpace: false`.
  */
-export declare function validateFile(filePath: string, config: Config): Promise<ValidateFileOutput>;
+export declare function validateFile(filePath: string, config: Config, options?: {
+    configDir?: string;
+}): Promise<ValidateFileOutput>;

package/dist/validate.js

@@ -1,9 +1,9 @@
 import { isAbsolute, relative, resolve } from 'node:path';
-import { getSpaceConfigDir, resolveSchema } from './config';
 import { readSpace } from './read/read-space';
-import { extractEntityInfo, loadSchema } from './schema/schema';
+import { extractEntityInfo } from './schema/schema';
 import { validateGraph } from './schema/validate-graph';
 import { validateRules } from './schema/validate-rules';
+import { createSpaceContext } from './space-context';
 import { buildSpaceGraph } from './space-graph';
 /**
  * Format AJV errors for better readability.
@@ -96,10 +96,10 @@ export function formatErrors(errors, schema, schemaRefRegistry, nodeData) {
  * Run full validation on a space and return a structured result.
  * Does not output to console or call process.exit.
  */
-export async function validateSpace(context) {
+export async function validateSpace(context, options = {}) {
     const { schema, schemaRefRegistry, schemaValidator } = context;
     const metadata = schema.metadata;
-    const readResult = await readSpace(context);
+    const readResult = options.readResult ?? (await readSpace(context));
     const { nodes, parseIssues } = readResult;
     // Pre-extract valid types for early type validation
     const validTypes = Array.isArray(schema.oneOf) ? extractEntityInfo(schema, schemaRefRegistry).map((e) => e.type) : [];
@@ -113,6 +113,7 @@ export async function validateSpace(context) {
         hierarchyViolations: [],
         orphans: [],
         parseIssues,
+        unresolvedContentLinks: [],
     };
     for (const node of nodes) {
         // Early type validation - check before full AJV validation to prevent cascading errors
@@ -174,6 +175,19 @@ export async function validateSpace(context) {
     if (metadata.rules) {
         result.ruleViolations = await validateRules(nodes, metadata.rules);
     }
+    // Collect unresolved content links (warnings — not errors)
+    const seen = new Set();
+    for (const node of nodes) {
+        for (const link of node.resolvedLinks) {
+            if (link.location === 'internal') {
+                const key = `${node.label}::${link.target}`;
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    result.unresolvedContentLinks.push({ file: node.label, target: link.target });
+                }
+            }
+        }
+    }
     return result;
 }
 /** Find which space a file belongs to by checking directory containment. */
@@ -189,12 +203,6 @@ function resolveFileSpace(filePath, config) {
     }
     return null;
 }
-function buildContextForSpace(space, config) {
-    const resolvedSchemaPath = resolveSchema(config, space);
-    const { schema, schemaRefRegistry, schemaValidator } = loadSchema(resolvedSchemaPath);
-    const configDir = getSpaceConfigDir(space.name);
-    return { space, config, resolvedSchemaPath, schema, schemaRefRegistry, schemaValidator, configDir };
-}
 /**
  * Validate a single file within its space.
  *
@@ -204,7 +212,7 @@ function buildContextForSpace(space, config) {
  * Returns a result object — does not output to console or call process.exit.
  * If the file is not in any configured space, returns a result with `inSpace: false`.
  */
-export async function validateFile(filePath, config) {
+export async function validateFile(filePath, config, options = {}) {
     const resolved = resolveFileSpace(filePath, config);
     if (!resolved) {
         return {
@@ -214,7 +222,7 @@ export async function validateFile(filePath, config) {
         };
     }
     const { space, label } = resolved;
-    const context = buildContextForSpace(space, config);
+    const context = createSpaceContext(space.name, config, { configDir: options.configDir });
     const { schema, schemaRefRegistry, schemaValidator } = context;
     const metadata = schema.metadata;
     const readResult = await readSpace(context);
@@ -280,12 +288,29 @@ export async function validateFile(filePath, config) {
             }
         }
     }
+    // Unresolved content links for this node (warnings — do not affect errorCount)
+    const warnings = {};
+    const targetNode = nodes.find((n) => n.label === label);
+    if (targetNode) {
+        const seen = new Set();
+        for (const link of targetNode.resolvedLinks) {
+            if (link.location === 'internal' && !seen.has(link.target)) {
+                seen.add(link.target);
+                warnings[`content-link:${link.target}`] = {
+                    kind: 'content-link',
+                    message: `Unresolved content link: ${link.target}`,
+                };
+            }
+        }
+    }
     return {
         file: isAbsolute(filePath) ? filePath : resolve(process.cwd(), filePath),
         label,
         space: space.name,
         errors,
         errorCount: Object.keys(errors).length,
+        warnings,
+        warningCount: Object.keys(warnings).length,
         inSpace: true,
     };
 }

package/docs/concepts.md

@@ -254,6 +254,29 @@ Each entry is a `ResolvedParentRef` object:
 
 The `source` label lets downstream consumers distinguish edge types without re-inspecting the schema. Validation routes `hierarchy` edges to structural checks (parent-type rules, skip-level detection) and `relationship` edges to field reference checks (type-match, missing-target). Tree rendering and rule evaluation use the full set.
 
+### Content links
+
+**Content links** (`resolvedLinks` on `SpaceNode`) are all links extracted from a node's content at parse time — both from frontmatter non-edge fields and from the body text. They are distinct from graph edges: they are never used to infer structure, but are available to consumers for rendering, auditing, or navigation.
+
+Each entry is a `ResolvedContentLink` object:
+
+| Field | Type | Description |
+|---|---|---|
+| `text` | `string` | Display text of the link |
+| `target` | `string` | Raw link target (URL or wikilink path) |
+| `action` | `'link' \| 'embed'` | Whether the link navigates or transcludes |
+| `anchor` | `string?` | Fragment component (heading or block ref) if present |
+| `location` | `'node' \| 'internal' \| 'external' \| 'system' \| 'protocol'` | Resolved location classification |
+
+**Location classification:**
+- `node` — wikilink resolved to a known space node
+- `internal` — wikilink or relative path to an in-source target that is not a space node
+- `external` — `http://` or `https://` URL
+- `system` — `file://` URL
+- `protocol` — any other scheme (e.g. `obsidian://`)
+
+**Sources:** Both wikilink syntax (`[[Target]]`, `![[Image]]`) and markdown link syntax (`[text](url)`, `![alt](url)`) are extracted. Bare URLs in frontmatter string fields are also captured. Graph edge fields (hierarchy `parent`, relationship fields) are excluded — those are graph edges, not content links.
+
 ### Anchor
 
 An **anchor** is a block anchor (e.g. `^goal1`) appended to a heading in a `typed page`, using Obsidian block anchor syntax. Anchors serve two purposes:

package/docs/config.md

@@ -28,6 +28,8 @@ A space is a named directory or single file registered in the config. Example:
 
 **`includeSpacesFrom`** — import space definitions from other config files. Useful for aggregating spaces from multiple projects into a central config. Duplicate space names are not allowed.
 
+A config must define at least one of `spaces` or `includeSpacesFrom`. When using `includeSpacesFrom` alone, `spaces` can be omitted entirely.
+
 ## Plugins
 
 Use `plugins` to load parse plugins that read spaces from non-markdown sources. The built-in markdown plugin is always available without any declaration. Plugins are tried in order; the first to return a result wins. The `plugins` field is a map of plugin name to plugin config, and can be declared at the top level (applies to all spaces) or per-space (overrides the top level):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "structured-context",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Keep your content clean and your thinking clear with assistive tools for structured knowledge",
   "module": "./dist/index.js",
   "type": "module",

package/schemas/_knowledge_wiki.json

@@ -207,7 +207,7 @@
     },
     "note": {
       "type": "object",
-      "description": "Personal notes, journal entries, appointments, experiential records. Your own data about your journey — not sourced from external material.",
+      "description": "Personal notes, journal entries, talk notes, or rough thoughts not drawn from an external URL.",
       "allOf": [{ "$ref": "sctx://_sctx_base#/$defs/baseNodeProps" }],
       "properties": {
         "type": { "const": "note" },

package/dist/integrations/miro/sync.d.ts

@@ -1,8 +0,0 @@
-import type { SpaceContext } from '../../types';
-interface SyncOptions {
-    newFrame?: string;
-    dryRun?: boolean;
-    verbose?: boolean;
-}
-export declare function miroSync(context: SpaceContext, options: SyncOptions): Promise<void>;
-export {};