structured-context 0.9.1 → 0.9.2

package/README.md

@@ -193,7 +193,7 @@ If no provider defines `hierarchy`, hierarchy-specific checks are skipped. Readi
 - **Transitive resolution**: `$ref` chains are resolved recursively across files/schemas (including nested `allOf` usage in partials).
 - **Unique IDs**: To encourage clean namespacing, local partial schemas **must** have unique `$id`s that do not collide with the default schemas. If a collision is detected, validation will fail with an error.
 
-Schema resolution order: space config `schema` > global config `schema` > bundled `schemas/general.json`
+Schema resolution order: space config `schema` > global config `schema`. Schema resolution fails if none is configured.
 
 **⚠️ Security Notice: Only use schemas and configuration files from trusted sources.**
 
@@ -322,7 +322,7 @@ Generates a Mermaid Entity Relationship Diagram from a schema:
 
 Example:
 ```bash
-sctx schemas show general --mermaid-erd
+sctx schemas show strategy_general --mermaid-erd
 ```
 
 ### Sync space to Miro

package/dist/commands/spaces.js

@@ -1,5 +1,5 @@
 import { basename, resolve } from 'node:path';
-import { configPath, loadConfig, resolveSchema } from '../config';
+import { configPath, loadConfig } from '../config';
 function renderConfigValue(v) {
     if (typeof v === 'object' && v !== null)
         return JSON.stringify(v);
@@ -12,7 +12,8 @@ export function listSpaces() {
     for (const space of config.spaces) {
         console.log(`${space.name}`);
         console.log(`  path:    ${space.path}`);
-        console.log(`  schema:  ${basename(resolveSchema(config, space))}`);
+        const schema = space.schema ?? config.schema;
+        console.log(`  schema:  ${schema ? basename(schema) : '(none)'}`);
         if (space.miroBoardId)
             console.log(`  miro:    configured`);
         const plugins = space.plugins ?? {};

package/dist/commands/validate.js

@@ -97,7 +97,7 @@ export async function validate(context, options = {}) {
     const { schema, schemaRefRegistry, schemaValidator } = context;
     const metadata = schema.metadata;
     const readResult = await readSpace(context);
-    const { nodes, parseIgnored } = readResult;
+    const { nodes, parseIssues } = readResult;
     const result = {
         validCount: 0,
         nodeErrorCount: 0,
@@ -107,7 +107,7 @@ export async function validate(context, options = {}) {
         ruleViolations: [],
         hierarchyViolations: [],
         orphans: [],
-        parseIgnored: parseIgnored || [],
+        parseIssues,
     };
     for (const node of nodes) {
         const valid = schemaValidator(node.schemaData);
@@ -180,7 +180,8 @@ export async function validate(context, options = {}) {
         for (const v of result.hierarchyViolations) {
             addError(v.file, `hierarchy:${v.description}`, 'hierarchy', v.description);
         }
-        const errorCount = Object.values(errorsByFile).reduce((sum, errs) => sum + Object.keys(errs).length, 0);
+        const parseErrorCount = result.parseIssues.filter((i) => i.severity === 'error').length;
+        const errorCount = Object.values(errorsByFile).reduce((sum, errs) => sum + Object.keys(errs).length, 0) + parseErrorCount;
         console.log(JSON.stringify({
             space: context.space.name,
             valid: errorCount === 0,
@@ -188,7 +189,7 @@ export async function validate(context, options = {}) {
             errorCount,
             errors: errorsByFile,
             orphanCount: result.orphans.length,
-            parseIgnored: result.parseIgnored,
+            parseIssues: result.parseIssues,
         }, null, 2));
         return errorCount > 0 ? 1 : 0;
     }
@@ -224,16 +225,19 @@ export async function validate(context, options = {}) {
     console.log(fmt('  Rule violations', result.ruleViolations.length, true));
     console.log(fmt('  Hierarchy violations', result.hierarchyViolations.length, true));
     console.log(fmt('  Orphans (hierarchy nodes - no parent)', result.orphans.length, true, true));
-    console.log(fmt('  Ignored during parsing', result.parseIgnored.length, true, true));
+    const parseIssueErrorCount = result.parseIssues.filter((i) => i.severity === 'error').length;
+    console.log(fmt('  Excluded during parsing', result.parseIssues.length, true, parseIssueErrorCount === 0));
     if (result.orphans.length > 0) {
         console.log(`\nOrphans (hierarchy nodes - no parent):`);
         for (const node of result.orphans)
             console.log(`   ${node.label}`);
     }
-    if (result.parseIgnored.length > 0) {
-        console.log(`\nIgnored during parsing:`);
-        for (const f of result.parseIgnored)
-            console.log(`   ${f}`);
+    if (result.parseIssues.length > 0) {
+        console.log(`\nExcluded during parsing:`);
+        for (const issue of result.parseIssues) {
+            const detail = issue.message ? ` - ${issue.message}` : '';
+            console.log(`   ${issue.file}: ${issue.severity} - ${issue.type}${detail}`);
+        }
     }
     if (result.nodeErrors.length > 0) {
         console.log(`\nSchema validation errors:`);
@@ -290,7 +294,8 @@ export async function validate(context, options = {}) {
         result.refErrors.length > 0 ||
         result.duplicateErrors.length > 0 ||
         result.ruleViolations.length > 0 ||
-        result.hierarchyViolations.length > 0) {
+        result.hierarchyViolations.length > 0 ||
+        parseIssueErrorCount > 0) {
         return 1;
     }
     return 0;

package/dist/config.d.ts

@@ -28,7 +28,7 @@ export declare function configPath(): string;
 export declare function loadConfig(): Config;
 /** Get the full space config entry by name. Throws if not found. */
 export declare function getSpaceConfig(name: string, config: Config): SpaceConfig;
-/** Resolve schema path: CLI arg > space-level config > global config > hardcoded default. */
+/** Resolve schema path: CLI arg > space-level config > global config. Throws if none configured. */
 export declare function resolveSchema(config: Config, space?: SpaceConfig): string;
 type StringFields<T> = {
     [K in keyof T]: T[K] extends string | undefined ? K : never;

package/dist/config.js

@@ -170,9 +170,13 @@ export function getSpaceConfig(name, config) {
     }
     return space;
 }
-/** Resolve schema path: CLI arg > space-level config > global config > hardcoded default. */
+/** Resolve schema path: CLI arg > space-level config > global config. Throws if none configured. */
 export function resolveSchema(config, space) {
-    return space?.schema ?? config.schema ?? join(bundledSchemasDir, 'general.json');
+    const schema = space?.schema ?? config.schema;
+    if (!schema) {
+        throw new Error('No schema configured. Set "schema" in the space config or at the top level of the config file.');
+    }
+    return schema;
 }
 /** Update a string field on a space entry and persist config. */
 export function updateSpaceField(spaceName, field, value) {

package/dist/plugin-api.d.ts

@@ -9,4 +9,4 @@ export type { AnySchemaObject, SchemaObject, ValidateFunction } from 'ajv';
 export type { ParseHook, ParseResult, PluginContext, RenderFormat, RenderHook, RenderOptions, StructuredContextPlugin, TemplateSyncHook, TemplateSyncOptions, } from './plugins/util';
 export type { SharedEmbeddingFields } from './schema/metadata-contract';
 export type { SpaceGraph } from './space-graph';
-export type { BaseNode, EdgeDefinition, HierarchyLevel, Relationship, SchemaMetadata, SchemaWithMetadata, SpaceContext, SpaceNode, UnresolvedRef, } from './types';
+export type { BaseNode, EdgeDefinition, HierarchyLevel, ParseIssue, Relationship, SchemaMetadata, SchemaWithMetadata, SpaceContext, SpaceNode, UnresolvedRef, } from './types';

package/dist/plugins/markdown/read-space.js

@@ -25,7 +25,13 @@ export function readSpaceOnAPage(context) {
         pageType: 'space_on_a_page',
         metadata,
     });
-    return { nodes, parseIgnored: terminatedHeadings, diagnostics: { kind: 'page', preambleNodeCount } };
+    const parseIssues = terminatedHeadings.map((heading) => ({
+        file: heading,
+        severity: 'warning',
+        type: 'terminated',
+        message: 'Ignored headings detected beyond end of hierarchy.',
+    }));
+    return { nodes, parseIssues, diagnostics: { kind: 'page', preambleNodeCount } };
 }
 export async function readSpaceDirectory(context, options) {
     const { space, schema: { metadata }, } = context;
@@ -38,17 +44,33 @@ export async function readSpaceDirectory(context, options) {
     const knownTypes = typeInferenceCfg?.mode !== 'off' ? extractSchemaTypeNames(context.schema, context.schemaRefRegistry) : undefined;
     const files = await Array.fromAsync(new Glob('**/*.md').scan({ cwd: directory, followSymlinks: true }));
     const nodes = [];
-    const skipped = [];
-    const nonSpace = [];
+    const parseIssues = [];
     for (const file of files) {
         const absoluteFilePath = resolve(directory, file);
         if (absoluteTemplateDir && absoluteFilePath.startsWith(absoluteTemplateDir)) {
             continue;
         }
         const content = readFileSync(join(directory, file), 'utf-8');
-        const parsed = matter(content);
+        let parsed;
+        try {
+            parsed = matter(content);
+        }
+        catch (err) {
+            // gray-matter caches parsed YAML and has a known bug where a caught exception
+            // corrupts its internal cache, causing subsequent parses to silently return {}.
+            // Clear the cache after any parse error to avoid stale state.
+            // See: https://github.com/jonschlinkert/gray-matter/issues/166
+            matter.clearCache();
+            parseIssues.push({
+                file,
+                severity: 'error',
+                type: 'parse',
+                message: err instanceof Error ? err.message : String(err),
+            });
+            continue;
+        }
         if (!parsed.data || Object.keys(parsed.data).length === 0) {
-            skipped.push(file);
+            parseIssues.push({ file, severity: 'warning', type: 'empty' });
             continue;
         }
         const data = coerceDates(applyFieldMap(parsed.data, fieldMap));
@@ -56,7 +78,7 @@ export async function readSpaceDirectory(context, options) {
             data.type = inferTypeFromPath(file, typeInferenceCfg, knownTypes, context.schema.metadata.typeAliases);
         }
         if (!data.type) {
-            nonSpace.push(file);
+            parseIssues.push({ file, severity: 'warning', type: 'no-type' });
             continue;
         }
         if (ON_A_PAGE_TYPES.includes(data.type) && !options?.includeOnAPageFiles) {
@@ -81,9 +103,14 @@ export async function readSpaceDirectory(context, options) {
             });
             nodes.push(...embedded);
             for (const heading of terminatedHeadings) {
-                nonSpace.push(`${file} > ${heading}`);
+                parseIssues.push({
+                    file: `${file} > ${heading}`,
+                    severity: 'warning',
+                    type: 'terminated',
+                    message: 'Ignored headings detected beyond end of hierarchy.',
+                });
             }
         }
     }
-    return { nodes, parseIgnored: [...skipped, ...nonSpace], diagnostics: { kind: 'directory' } };
+    return { nodes, parseIssues, diagnostics: { kind: 'directory' } };
 }

package/dist/plugins/util.d.ts

@@ -1,6 +1,6 @@
 import type { AnySchemaObject } from 'ajv';
 import type { SpaceGraph } from '../space-graph';
-import type { BaseNode, SpaceContext } from '../types';
+import type { BaseNode, ParseIssue, SpaceContext } from '../types';
 export declare const PLUGIN_PREFIX = "sctx-";
 export declare const CONFIG_PLUGINS_DIR = "plugins";
 /** Normalize a plugin name to its canonical prefixed form. */
@@ -11,8 +11,8 @@ export type PluginContext = SpaceContext & {
 };
 export type ParseResult = {
     nodes: BaseNode[];
-    /** Paths/items the plugin skipped during parsing, for any reason. */
-    parseIgnored: string[];
+    /** Issues encountered while parsing files — excluded files with reason and severity. */
+    parseIssues: ParseIssue[];
     /** Plugin diagnostics: keyed scalar or list values. */
     diagnostics: Record<string, number | string | string[]>;
 };

package/dist/read/read-space.js

@@ -12,7 +12,7 @@ export async function readSpace(context) {
             return {
                 nodes,
                 source: plugin.name,
-                parseIgnored: result.parseIgnored,
+                parseIssues: result.parseIssues,
                 diagnostics: result.diagnostics,
                 unresolvedRefs,
             };

package/dist/schemas/{general.json → strategy_general.json}

@@ -1,6 +1,6 @@
 {
   "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json",
-  "$id": "sctx://general",
+  "$id": "sctx://strategy_general",
   "title": "Strategy and opportunity ladder",
   "description": "Validates frontmatter for space node files",
   "$metadata": {

package/dist/types.d.ts

@@ -86,6 +86,18 @@ export type SpaceNode = BaseNode & {
      */
     resolvedParents: ResolvedParentRef[];
 };
+export type ParseIssue = {
+    /** Source identifier of the file or item (filename or heading title). */
+    file: string;
+    /** error: prevented the file from producing nodes; warning: file was silently excluded. */
+    severity: 'error' | 'warning';
+    /** empty: no content; no-type: no type field;
+     *  parse: parse failure (syntax issue or unexpected content);
+     *  plugins may choose to provide additional types. */
+    type: 'empty' | 'no-type' | 'parse' | string;
+    /** Human-readable detail. */
+    message?: string;
+};
 /** Rule categories for organizing executable validation rules */
 export type RuleCategory = 'validation' | 'coherence' | 'workflow' | 'best-practice';
 export type { Rule } from './schema/metadata-contract';
@@ -118,8 +130,8 @@ export type SchemaWithMetadata = SchemaObject & {
 export type ReadSpaceResult = {
     /** Fully resolved nodes produced by the plugin and enriched by core. */
     nodes: SpaceNode[];
-    /** Paths/items the plugin skipped during parsing, for any reason. */
-    parseIgnored: string[];
+    /** Issues encountered while parsing files — excluded files with reason and severity. */
+    parseIssues: ParseIssue[];
     /** Plugin diagnostics: keyed scalar or list values. */
     diagnostics: Record<string, number | string | string[]>;
     /** Name of the plugin that produced the nodes. */

package/docs/config.md

@@ -20,7 +20,7 @@ A space is a named directory or single file registered in the config. Example:
     {
       "name": "ProductX",
       "path": "/path/to/space",
-      "schema": "general.json"
+      "schema": "strategy_general.json"
     }
   ]
 }

package/docs/schemas.md

@@ -20,11 +20,11 @@ Set `schema` in the space config entry:
 }
 ```
 
-Resolution order: space `schema` > global `schema` > bundled `schemas/general.json`.
+Resolution order: space `schema` > global `schema`. Schema resolution fails if none is configured.
 
 ## Bundled schemas
 
-### `general.json` (default)
+### `strategy_general.json`
 
 Flexible planning schema spanning strategy + OST-like flow.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "structured-context",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Tools for working with Opportunity Solution Tree structures and other product management and strategy frameworks",
   "module": "./dist/index.js",
   "type": "module",

package/schemas/{general.json → strategy_general.json}

@@ -1,6 +1,6 @@
 {
   "$schema": "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json",
-  "$id": "sctx://general",
+  "$id": "sctx://strategy_general",
   "title": "Strategy and opportunity ladder",
   "description": "Validates frontmatter for space node files",
   "$metadata": {