structured-context 0.15.0 → 0.16.0

package/README.md

@@ -188,6 +188,14 @@ Generates a Mermaid `graph TD` diagram from validated space nodes:
 - Handles orphan nodes (no parent) as a separate cluster
 - Outputs to file or stdout
 
+### List schemas
+
+```bash
+sctx schemas list [--json]
+```
+
+Lists the bundled schemas, schemas contributed by plugins, and any other schema file your config uses, with the spaces that use each. `--json` gives the data that `listSchemas` returns; see [docs/api.md](docs/api.md).
+
 ### Show schema ERD
 
 ```bash

package/dist/api.d.ts

@@ -27,6 +27,7 @@ export type { ParseHook, ParseResult, PluginContext, RenderFileOutput, RenderFor
 export { isRenderMultiFileOutput, resolvePluginDir, resolvePluginSchemasDir, resolveSpacePluginSchemas, } from './plugins/util';
 export { readSpace } from './read/read-space';
 export { buildTargetIndex, formatWikilink, type ParsedWikilink, parseWikilink, wikilinkToTarget, } from './read/wikilink-utils';
+export { listSchemas } from './schema/list-schemas';
 export type { SharedEmbeddingFields } from './schema/metadata-contract';
 export { bundledSchemasDir, loadSchema, type PluginSchemaSource, setBundledSchemasDir } from './schema/schema';
 export { createSpaceContext, SpaceNotFoundError } from './space-context';

package/dist/api.js

@@ -1,3 +1,4 @@
+// Public entry point: do not add exports without the maintainer's agreement (AGENTS.md, "Public API surface").
 /**
  * Public API for structured-context.
  *
@@ -24,6 +25,7 @@ export { assembleSpaceGraph, loadSpaceGraph } from './load-space-graph';
 export { isRenderMultiFileOutput, resolvePluginDir, resolvePluginSchemasDir, resolveSpacePluginSchemas, } from './plugins/util';
 export { readSpace } from './read/read-space';
 export { buildTargetIndex, formatWikilink, parseWikilink, wikilinkToTarget, } from './read/wikilink-utils';
+export { listSchemas } from './schema/list-schemas';
 export { bundledSchemasDir, loadSchema, setBundledSchemasDir } from './schema/schema';
 export { createSpaceContext, SpaceNotFoundError } from './space-context';
 export { buildSpaceGraph } from './space-graph';

package/dist/commands/schemas.d.ts

@@ -1,4 +1,6 @@
-export declare function listSchemas(): Promise<void>;
+export declare function printSchemas(options?: {
+    json?: boolean;
+}): Promise<void>;
 export declare function showSchema(file: string | undefined, options: {
     space?: string;
     raw: boolean;

package/dist/commands/schemas.js

@@ -1,16 +1,14 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { join, resolve } from 'node:path';
 import { loadConfig } from '../config';
 import { discoverPlugins } from '../plugins/loader';
 import { normalizePluginName, resolvePluginSchemasDir, resolveSpacePluginSchemas, shortenPluginName, } from '../plugins/util';
+import { listSchemas } from '../schema/list-schemas';
 import { ruleSemantic } from '../schema/rule-severity';
 import { bundledSchemasDir, extractEntityInfo, loadSchema, readRawSchema, } from '../schema/schema';
 import { mergeVariantProperties, resolveRef } from '../schema/schema-refs';
 import { DEFAULT_SEVERITY_BY_CATEGORY } from '../schema/validate-rules';
 import { createSpaceContext } from '../space-context';
-function isBundledPath(schemaPath) {
-    return dirname(schemaPath) === bundledSchemasDir;
-}
 function extractRefs(obj, refs) {
     if (typeof obj !== 'object' || obj === null)
         return;
@@ -207,57 +205,30 @@ function ruleAnnotations(rule) {
         notes.push(`when: ${rule.when}`);
     return notes.length > 0 ? ` [${notes.join('] [')}]` : '';
 }
-export async function listSchemas() {
-    const config = loadConfig();
-    // List all schemas known to config
-    if (existsSync(bundledSchemasDir)) {
-        const files = readdirSync(bundledSchemasDir)
-            .filter((f) => f.endsWith('.json'))
-            .sort();
-        if (files.length > 0) {
-            console.log('Bundled schemas:');
-            for (const file of files) {
-                const schema = readRawSchema(join(bundledSchemasDir, file));
-                const id = typeof schema.$id === 'string' ? schema.$id : '(no $id)';
-                console.log(`  ${file}${file.startsWith('_') ? '  [partial]' : ''}  (${id})`);
-            }
-        }
+export async function printSchemas(options = {}) {
+    const listings = await listSchemas();
+    if (options.json) {
+        console.log(JSON.stringify(listings, null, 2));
+        return;
     }
-    // List schemas provided by discovered plugins
-    const plugins = await discoverPlugins();
-    for (const p of plugins) {
-        if (p.schemasDir && existsSync(p.schemasDir)) {
-            const files = readdirSync(p.schemasDir)
-                .filter((f) => f.endsWith('.json'))
-                .sort();
-            if (files.length > 0) {
-                console.log(`\nPlugin schemas (${p.name}):`);
-                for (const file of files) {
-                    const schema = readRawSchema(join(p.schemasDir, file));
-                    const id = typeof schema.$id === 'string' ? schema.$id : '(no $id)';
-                    console.log(`  ${file}${file.startsWith('_') ? '  [partial]' : ''}  (${id})`);
-                }
+    const sources = [...new Set(listings.map((l) => l.source))].sort((a, b) => Number(b === 'core') - Number(a === 'core') || Number(a === 'configured') - Number(b === 'configured'));
+    for (const source of sources) {
+        const group = listings.filter((l) => l.source === source);
+        if (source === 'core')
+            console.log('Bundled schemas:');
+        else if (source === 'configured')
+            console.log('\nConfigured schemas:');
+        else
+            console.log(`\nPlugin schemas (${source}):`);
+        for (const l of group) {
+            if (source === 'configured')
+                console.log(`  ${l.usedBy.join(', ')}: ${l.path ?? l.schema}${l.error ? `  [${l.error}]` : ''}`);
+            else {
+                const notes = [l.partial && '[partial]', l.id && `(${l.id})`, l.error && `[${l.error}]`].filter(Boolean);
+                console.log(`  ${l.schema}${notes.length > 0 ? `  ${notes.join('  ')}` : ''}`);
             }
         }
     }
-    const configured = [];
-    const seen = new Set();
-    if (config.schema && !isBundledPath(config.schema)) {
-        configured.push({ source: 'global', path: config.schema });
-        seen.add(config.schema);
-    }
-    for (const space of config.spaces) {
-        if (space.schema && !seen.has(space.schema) && !isBundledPath(space.schema)) {
-            configured.push({ source: space.name, path: space.schema });
-            seen.add(space.schema);
-        }
-    }
-    if (configured.length > 0) {
-        console.log('\nConfigured schemas:');
-        for (const { source, path } of configured) {
-            console.log(`  ${source}: ${path}`);
-        }
-    }
 }
 export async function showSchema(file, options) {
     const config = loadConfig();

package/dist/index.js

@@ -8,7 +8,7 @@ import { dump } from './commands/dump';
 import { miroSyncCommand } from './commands/miro-sync';
 import { listPlugins } from './commands/plugins';
 import { render, renderList } from './commands/render';
-import { listSchemas, showSchema } from './commands/schemas';
+import { printSchemas, showSchema } from './commands/schemas';
 import { show } from './commands/show';
 import { addSpaceCommand, listSpaces } from './commands/spaces';
 import { templateSync } from './commands/template-sync';
@@ -176,7 +176,8 @@ const schemasCmd = new Command('schemas').alias('schema').description('List and
 schemasCmd
     .command('list', { isDefault: true })
     .description('List available schemas')
-    .action(async () => await listSchemas());
+    .option('--json', 'Output as JSON')
+    .action(async (options) => await printSchemas({ json: options.json ?? false }));
 schemasCmd
     .command('show')
     .description('Show schema structure (or raw JSON with --raw, or Mermaid ERD with --mermaid-erd)')

package/dist/schema/list-schemas.d.ts

@@ -0,0 +1,27 @@
+import { type Config } from '../config';
+type SchemaListing = {
+    /** The value for a config's `schema` field. */
+    schema: string;
+    /** Absolute location or URL. Omitted for bundled schemas. */
+    path?: string;
+    /** `core`, a plugin's short name, or `configured`. */
+    source: string;
+    /** Names of the spaces that use it, and `global` when the top-level `schema` does. */
+    usedBy: string[];
+    partial: boolean;
+    id?: string;
+    title?: string;
+    description?: string;
+    /** Why the schema could not be read. */
+    error?: string;
+};
+/**
+ * List the schemas available to the config: bundled schemas, schemas contributed by plugins, and any other
+ * schema file the config points at. Each schema appears once, under the place its file lives.
+ */
+export declare function listSchemas(options?: {
+    /** Loaded by discovery from `startDir` when omitted. */
+    config?: Config;
+    startDir?: string;
+}): Promise<SchemaListing[]>;
+export {};

package/dist/schema/list-schemas.js

@@ -0,0 +1,108 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { loadConfig, resolveConfigPath, resolveSchemaPath } from '../config';
+import { PLUGIN_PREFIX } from '../constants';
+import { CONFIG_PLUGINS_DIR, resolvePluginSchemasDir, resolveSpacePluginSchemas, shortenPluginName, } from '../plugins/util';
+import { bundledSchemasDir, readRawSchema } from './schema';
+function isRemote(ref) {
+    return /^https?:\/\//.test(ref);
+}
+function describeSchema(path) {
+    try {
+        const schema = readRawSchema(path);
+        return {
+            ...(typeof schema.$id === 'string' && { id: schema.$id }),
+            ...(typeof schema.title === 'string' && { title: schema.title }),
+            ...(typeof schema.description === 'string' && { description: schema.description }),
+        };
+    }
+    catch (e) {
+        return { error: e instanceof Error ? e.message : String(e) };
+    }
+}
+function jsonFiles(dir) {
+    if (!dir || !existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => f.endsWith('.json'))
+        .sort();
+}
+/**
+ * List the schemas available to the config: bundled schemas, schemas contributed by plugins, and any other
+ * schema file the config points at. Each schema appears once, under the place its file lives.
+ */
+export async function listSchemas(options = {}) {
+    const config = options.config ?? loadConfig({ startDir: options.startDir });
+    const listings = [];
+    const byPath = new Map();
+    const add = (listing, location) => {
+        listings.push(listing);
+        byPath.set(resolve(location), listing);
+    };
+    for (const file of jsonFiles(bundledSchemasDir)) {
+        const location = join(bundledSchemasDir, file);
+        add({ schema: file, source: 'core', usedBy: [], partial: file.startsWith('_'), ...describeSchema(location) }, location);
+    }
+    // Relative schema references are anchored at the folder of the config that holds them
+    const fallbackDir = dirname(resolveConfigPath(options.startDir).path);
+    const configDirs = [...new Set([fallbackDir, ...config.spaces.map((s) => s.sourceDir ?? fallbackDir)])];
+    // Plugins are found the way schema references resolve them, without loading their code: those declared by a
+    // space or the config, and any installed beside a config file
+    const pluginSchemaDirs = new Map();
+    for (const space of [undefined, ...config.spaces]) {
+        for (const { pluginName, schemasDir } of resolveSpacePluginSchemas(space, config, space?.sourceDir ?? fallbackDir)) {
+            pluginSchemaDirs.set(pluginName, schemasDir);
+        }
+    }
+    for (const dir of configDirs) {
+        const pluginsDir = join(dir, CONFIG_PLUGINS_DIR);
+        if (!existsSync(pluginsDir))
+            continue;
+        for (const entry of readdirSync(pluginsDir).filter((e) => e.startsWith(PLUGIN_PREFIX))) {
+            const schemasDir = resolvePluginSchemasDir(entry, dir);
+            if (schemasDir && !pluginSchemaDirs.has(shortenPluginName(entry))) {
+                pluginSchemaDirs.set(shortenPluginName(entry), schemasDir);
+            }
+        }
+    }
+    for (const [source, schemasDir] of pluginSchemaDirs) {
+        for (const file of jsonFiles(schemasDir)) {
+            const location = join(schemasDir, file);
+            add({
+                schema: `${source}/${file}`,
+                path: location,
+                source,
+                usedBy: [],
+                partial: file.startsWith('_'),
+                ...describeSchema(location),
+            }, location);
+        }
+    }
+    const references = [
+        ...(config.schema ? [{ user: 'global', raw: config.schema, dir: fallbackDir }] : []),
+        ...config.spaces.flatMap((s) => s.schema ? [{ user: s.name, raw: s.schema, dir: s.sourceDir ?? fallbackDir }] : []),
+    ];
+    for (const { user, raw, dir } of references) {
+        const location = isRemote(raw) ? raw : resolveSchemaPath(raw, dir);
+        const key = isRemote(raw) ? raw : resolve(location);
+        let listing = byPath.get(key);
+        if (!listing) {
+            listing = {
+                schema: raw,
+                path: isRemote(raw) || isAbsolute(location) ? location : resolve(location),
+                source: 'configured',
+                usedBy: [],
+                partial: basename(raw).startsWith('_'),
+                ...(isRemote(raw)
+                    ? { error: 'Remote schemas are not read' }
+                    : existsSync(location)
+                        ? describeSchema(location)
+                        : { error: `Schema file not found: ${location}` }),
+            };
+            add(listing, key);
+        }
+        if (!listing.usedBy.includes(user))
+            listing.usedBy.push(user);
+    }
+    return listings;
+}

package/package.json

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