@prongsjs/core 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Drew Poling
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @prongsjs/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Prongs intent spec: typed intent registries, profiles, and the engine behind `prongs check` and `PRONGS.md`. It knows nothing about UI; `@prongsjs/ui`, `@prongsjs/errors` and `@prongsjs/logs` are profiles built on it.
+
+You usually get it through `npx prongs add`. Early (0.x): expect changes. Full guide: https://github.com/drewpoling2/prongs#readme

package/dist/engine/baseline.d.ts

@@ -0,0 +1,17 @@
+import type { Violation } from './types.js';
+/**
+ * A baseline records existing violations so a project can adopt checks without
+ * fixing everything first. Only new violations fail; the count can only go down.
+ * Entries are keyed by rule, file, intent and source line text (not line numbers),
+ * so unrelated edits that shift lines do not invalidate the baseline.
+ */
+export type Baseline = {
+    version: 1;
+    entries: Record<string, number>;
+};
+export declare function fingerprint(v: Violation): string;
+export declare function createBaseline(violations: readonly Violation[]): Baseline;
+export declare function applyBaseline(violations: readonly Violation[], baseline: Baseline): {
+    fresh: Violation[];
+    baselined: Violation[];
+};

package/dist/engine/baseline.js

@@ -0,0 +1,29 @@
+export function fingerprint(v) {
+    return [v.rule, v.path, v.intent ?? '', v.snippet.replace(/\s+/g, ' ')].join('|');
+}
+export function createBaseline(violations) {
+    const entries = {};
+    for (const v of violations) {
+        if (v.severity === 'info')
+            continue;
+        const key = fingerprint(v);
+        entries[key] = (entries[key] ?? 0) + 1;
+    }
+    return { version: 1, entries: Object.fromEntries(Object.entries(entries).sort()) };
+}
+export function applyBaseline(violations, baseline) {
+    const remaining = { ...baseline.entries };
+    const fresh = [];
+    const baselined = [];
+    for (const v of violations) {
+        const key = fingerprint(v);
+        if (v.severity !== 'info' && (remaining[key] ?? 0) > 0) {
+            remaining[key]--;
+            baselined.push(v);
+        }
+        else {
+            fresh.push(v);
+        }
+    }
+    return { fresh, baselined };
+}

package/dist/engine/check.d.ts

@@ -0,0 +1,4 @@
+import type { AnyRegistry } from '../registry.js';
+import type { ProfileTooling, SourceFile, Violation } from './types.js';
+/** Runs every applicable profile's usages, per-intent checks and rules over the files. */
+export declare function checkFiles(files: readonly SourceFile[], registry: AnyRegistry, toolings: readonly ProfileTooling[]): Violation[];

package/dist/engine/check.js

@@ -0,0 +1,90 @@
+import { intentsUsing, nearestIntents } from './util.js';
+/** Checks collected along the intent's ref chain, own checks last. */
+function checksFor(registry, id, seen = new Set()) {
+    if (seen.has(id) || !registry.has(id))
+        return [];
+    seen.add(id);
+    const intent = registry.defs[id];
+    return [
+        ...(intent.refs ?? []).flatMap((ref) => checksFor(registry, ref, seen)),
+        ...(intent.checks ?? []),
+    ];
+}
+function usageViolation(usage, rule, message, suggestions) {
+    return {
+        rule,
+        severity: 'error',
+        path: usage.path,
+        line: usage.line,
+        column: usage.column,
+        snippet: usage.snippet,
+        intent: usage.intent,
+        message,
+        suggestions,
+    };
+}
+function checkUsage(ctx, tooling, usage) {
+    const { registry } = ctx;
+    if (!registry.has(usage.intent)) {
+        return [
+            usageViolation(usage, 'unknown-intent', `Unknown intent "${usage.intent}".`, nearestIntents(registry, usage.intent).map((id) => ({
+                intent: id,
+                text: registry.defs[id].description,
+            }))),
+        ];
+    }
+    if (registry.isInternal(usage.intent)) {
+        return [
+            usageViolation(usage, 'internal-intent', `"${usage.intent}" describes a look and can only be used as a ref. Pick an intent by what this element does.`, intentsUsing(registry, usage.intent).map((id) => ({
+                intent: id,
+                text: registry.defs[id].description,
+            }))),
+        ];
+    }
+    const violations = [];
+    const intent = registry.defs[usage.intent];
+    if (intent.status === 'deprecated') {
+        const instead = intent.notFor?.find((e) => e.instead)?.instead;
+        violations.push({
+            ...usageViolation(usage, 'deprecated-intent', `"${usage.intent}" is deprecated.`, []),
+            severity: 'warning',
+            suggestions: instead ? [{ intent: instead, text: registry.defs[instead].description }] : [],
+        });
+    }
+    for (const check of checksFor(registry, usage.intent)) {
+        const impl = tooling.checks?.[check.type];
+        if (!impl) {
+            violations.push({
+                ...usageViolation(usage, 'unknown-check', `No "${tooling.name}" check named "${check.type}".`, []),
+                severity: 'warning',
+            });
+            continue;
+        }
+        violations.push(...impl({ check, intentId: usage.intent, intent, usage, ctx }));
+    }
+    return violations;
+}
+/** Runs every applicable profile's usages, per-intent checks and rules over the files. */
+export function checkFiles(files, registry, toolings) {
+    const violations = [];
+    for (const file of files) {
+        for (const tooling of toolings) {
+            if (!tooling.appliesTo(file.path))
+                continue;
+            const ctx = { registry, file };
+            for (const usage of tooling.findUsages(ctx)) {
+                violations.push(...checkUsage(ctx, tooling, usage));
+            }
+            for (const rule of tooling.rules ?? [])
+                violations.push(...rule.run(ctx));
+        }
+    }
+    for (const tooling of toolings) {
+        if (!tooling.projectRules?.length)
+            continue;
+        const own = files.filter((f) => tooling.appliesTo(f.path));
+        for (const rule of tooling.projectRules)
+            violations.push(...rule.run({ registry, files: own }));
+    }
+    return violations.sort((a, b) => a.path.localeCompare(b.path) || a.line - b.line || a.column - b.column);
+}

package/dist/engine/find.d.ts

@@ -0,0 +1,20 @@
+import type { AnyRegistry } from '../registry.js';
+export type FoundIntent = {
+    id: string;
+    score: number;
+    /** Set when the query matched another intent's "not for" line that points here. */
+    via?: string;
+};
+/** Lower-case words, camelCase split, without stop words. */
+export declare function words(text: string): string[];
+/** A rough stem, so delete/deleting/deleted and invite/invitation meet. */
+export declare function stem(word: string): string;
+/**
+ * Ranks a registry's call-site intents against a description of what something is for
+ * ("wrong email or password", "close the banner"). The meaning in the id counts most,
+ * then keywords, then the description; a description that covers the whole question gets
+ * a bonus. A question that matches an intent's "not for" line, on words that set that
+ * line apart from the intent itself, pushes the intent down and the one it points to up,
+ * the way an agent is told to read them. `textOf` adds what tooling knows (`404`, `<h1>`).
+ */
+export declare function findIntents(registry: AnyRegistry, query: string, limit?: number, textOf?: (id: string) => string): FoundIntent[];

package/dist/engine/find.js

@@ -0,0 +1,81 @@
+/** Words that say nothing about what something is for. */
+const STOP = new Set('a an the of for to in on at by with from or and is are be it its this that these those my your our their when what which who how not no do does something someone some any every each one'.split(' '));
+/** Lower-case words, camelCase split, without stop words. */
+export function words(text) {
+    return text
+        .replace(/([a-z])([A-Z])/g, '$1 $2')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((w) => w.length > 1 && !STOP.has(w));
+}
+/** A rough stem, so delete/deleting/deleted and invite/invitation meet. */
+export function stem(word) {
+    return word.replace(/(ations?|ings?|ed|es|s|er|ers|ion|ions)$/, '').replace(/e$/, '') || word;
+}
+/**
+ * Ranks a registry's call-site intents against a description of what something is for
+ * ("wrong email or password", "close the banner"). The meaning in the id counts most,
+ * then keywords, then the description; a description that covers the whole question gets
+ * a bonus. A question that matches an intent's "not for" line, on words that set that
+ * line apart from the intent itself, pushes the intent down and the one it points to up,
+ * the way an agent is told to read them. `textOf` adds what tooling knows (`404`, `<h1>`).
+ */
+export function findIntents(registry, query, limit = 3, textOf) {
+    const raw = query.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+    const terms = new Set(words(query).map(stem));
+    if (terms.size === 0)
+        return [];
+    // "sign out" also asks for `signout`, "signed in" for `signedin`.
+    const joined = new Set(raw.slice(1).map((w, i) => stem(raw[i] + w)));
+    const asked = new Set([...terms, ...joined]);
+    const scores = new Map();
+    const bump = (id, by, via) => {
+        const current = scores.get(id) ?? { id, score: 0 };
+        current.score += by;
+        if (via && by > 0)
+            current.via = via;
+        scores.set(id, current);
+    };
+    for (const id of registry.ids) {
+        if (registry.isInternal(id))
+            continue;
+        const intent = registry.defs[id];
+        const [domain, ...meaning] = id.split('.');
+        const meaningWords = new Set(meaning.flatMap(words).map(stem));
+        const keywordWords = new Set((intent.keywords ?? []).flatMap(words).map(stem));
+        const describedWords = new Set([...words(intent.description), ...words(textOf?.(id) ?? '')].map(stem));
+        let score = 0;
+        for (const w of asked) {
+            if (meaningWords.has(w))
+                score += 6;
+            else if (keywordWords.has(w))
+                score += 4;
+            else if (describedWords.has(w))
+                score += 2;
+        }
+        if (asked.has(stem(domain)))
+            score += 2;
+        const own = new Set([...meaningWords, ...keywordWords, ...describedWords, stem(domain)]);
+        const covered = [...terms].filter((w) => own.has(w)).length;
+        if (terms.size > 1 && covered === terms.size)
+            score += 4;
+        if (score > 0)
+            bump(id, score);
+        // A "not for" line moves the answer only on words that set it apart from this intent.
+        for (const e of (intent.notFor ?? [])) {
+            const distinct = words(e.context)
+                .map(stem)
+                .filter((w) => asked.has(w) && !own.has(w));
+            const hits = new Set(distinct).size;
+            if (hits === 0 || hits / terms.size < 0.5)
+                continue;
+            bump(id, -hits * 4);
+            if (e.instead && registry.has(e.instead) && !registry.isInternal(e.instead))
+                bump(e.instead, hits * 5, id);
+        }
+    }
+    return [...scores.values()]
+        .filter((f) => f.score > 0)
+        .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id))
+        .slice(0, limit);
+}

package/dist/engine/index.d.ts

@@ -0,0 +1,10 @@
+export { checkFiles } from './check.js';
+export { applyBaseline, createBaseline, fingerprint } from './baseline.js';
+export type { Baseline } from './baseline.js';
+export { compileReference, compileSpec } from './spec-md.js';
+export { findIntents } from './find.js';
+export type { FoundIntent } from './find.js';
+export type { CompileSpecOptions } from './spec-md.js';
+export { editDistance, intentsUsing, locate, nearestIntents } from './util.js';
+export type { CheckImpl, ProfileTooling, ProjectRule, Rule, RuleDoc, Severity, SourceFile, SpecContext, SpecTooling, Suggestion, ToolingContext, Usage, Violation, } from './types.js';
+export { CORE_RULE_DOCS } from './rule-docs.js';

package/dist/engine/index.js

@@ -0,0 +1,6 @@
+export { checkFiles } from './check.js';
+export { applyBaseline, createBaseline, fingerprint } from './baseline.js';
+export { compileReference, compileSpec } from './spec-md.js';
+export { findIntents } from './find.js';
+export { editDistance, intentsUsing, locate, nearestIntents } from './util.js';
+export { CORE_RULE_DOCS } from './rule-docs.js';

package/dist/engine/rule-docs.d.ts

@@ -0,0 +1,3 @@
+import type { RuleDoc } from './types.js';
+/** Rules the engine applies to every profile's usages. */
+export declare const CORE_RULE_DOCS: readonly RuleDoc[];

package/dist/engine/rule-docs.js

@@ -0,0 +1,31 @@
+/** Rules the engine applies to every profile's usages. */
+export const CORE_RULE_DOCS = [
+    {
+        id: 'unknown-intent',
+        profile: 'core',
+        severity: 'error',
+        summary: 'An intent that is not in the registry. Suggests the closest names, so a typo is one step from the fix.',
+        bad: "<Action intent=\"action.delet\">Delete</Action>",
+        good: "<Action intent=\"action.delete\">Delete</Action>",
+    },
+    {
+        id: 'internal-intent',
+        profile: 'core',
+        severity: 'error',
+        summary: 'A ref-only intent (a look, a status, a level) used where code should name a meaning. Suggests the meaning intents built on it.',
+        bad: '<Action intent="control.primary">Save</Action>',
+        good: '<Action intent="action.save">Save</Action>',
+    },
+    {
+        id: 'deprecated-intent',
+        profile: 'core',
+        severity: 'warning',
+        summary: 'An intent marked deprecated. Suggests the intent its "not for" line points to.',
+    },
+    {
+        id: 'unknown-check',
+        profile: 'core',
+        severity: 'warning',
+        summary: 'An intent asks for a per-intent check its profile does not implement.',
+    },
+];

package/dist/engine/spec-md.d.ts

@@ -0,0 +1,24 @@
+import type { AnyRegistry } from '../registry.js';
+import type { SpecTooling } from './types.js';
+export type CompileSpecOptions = {
+    /** Where the registry lives, mentioned in the header so readers know what to edit. */
+    registryPath?: string;
+    /** How to run the CLI in this project. */
+    cli?: string;
+    /** The import path of the project's components, e.g. `@/components/prongs`. */
+    componentsImport?: string;
+    /**
+     * A second file for what only changing the system needs (theme, look intents). With it,
+     * PRONGS.md keeps what building needs and points there; without it, everything is in one file.
+     */
+    referenceFile?: string;
+};
+/**
+ * Builds PRONGS.md: the index agents choose intents from, the profiles' own rules and
+ * examples, then the look-only intents new intents are built from. It leaves out
+ * resolved class strings: agents never write them, and the registry already has them.
+ * Works for any profile; tooling adds its own sections.
+ */
+export declare function compileSpec(registry: AnyRegistry, toolings: readonly SpecTooling[], options?: CompileSpecOptions): string;
+/** The reference file: what editing the theme or adding intents needs, and building does not. */
+export declare function compileReference(registry: AnyRegistry, toolings: readonly SpecTooling[], options?: CompileSpecOptions): string;

package/dist/engine/spec-md.js

@@ -0,0 +1,76 @@
+import { domainOf } from '../spec.js';
+/**
+ * Builds PRONGS.md: the index agents choose intents from, the profiles' own rules and
+ * examples, then the look-only intents new intents are built from. It leaves out
+ * resolved class strings: agents never write them, and the registry already has them.
+ * Works for any profile; tooling adds its own sections.
+ */
+export function compileSpec(registry, toolings, options = {}) {
+    const cli = options.cli ?? 'npx prongs';
+    const toolingFor = (id) => toolings.find((t) => t.name === registry.profileOf(id).name);
+    const out = [];
+    out.push('# PRONGS.md', '');
+    out.push(`Generated from \`${options.registryPath ?? 'the intent registry'}\` by \`${cli} spec\`. Do not edit by hand.`, '');
+    out.push('## How to choose an intent', '', '1. Pick the intent whose description matches what the element or code is *for*, not how it should look.', '2. Read its "not for" lines. If one matches your case, use the intent it points to.', `3. If nothing fits, add one instead of working around the system: \`${cli} add-intent <domain.meaning> --description "..." --refs <closest>\`.`, `4. \`${cli} check\` verifies usage. In projects with hooks installed it runs after every edit.`, '');
+    out.push('## Intents', '');
+    const callSite = registry.ids.filter((id) => !registry.isInternal(id));
+    const groups = new Map();
+    for (const id of callSite) {
+        const group = toolingFor(id)?.groupOf?.(id) ?? `\`${domainOf(id)}\``;
+        groups.set(group, [...(groups.get(group) ?? []), id]);
+    }
+    for (const [group, ids] of groups) {
+        out.push(`### ${group}`, '');
+        for (const id of ids) {
+            const intent = registry.defs[id];
+            const flag = intent.status && intent.status !== 'stable' ? ` _(${intent.status})_` : '';
+            const renders = toolingFor(id)?.describe?.(registry.resolve(id).binding);
+            out.push(`- \`${id}\`${renders ? ` ${renders}` : ''}${flag}: ${intent.description}`);
+            if (intent.keywords?.length)
+                out.push(`  - matches code that says: ${intent.keywords.join(', ')}`);
+            for (const e of (intent.notFor ?? [])) {
+                out.push(`  - not for ${e.context}${e.instead ? `: use \`${e.instead}\`` : ''}${e.reason ? ` (${e.reason})` : ''}`);
+            }
+        }
+        out.push('');
+    }
+    for (const tooling of toolings) {
+        const section = tooling.specSection?.(registry, { cli, componentsImport: options.componentsImport });
+        if (section)
+            out.push(section.trim(), '');
+    }
+    if (options.referenceFile) {
+        out.push('## Changing the system', '', `To edit the theme or add an intent, read \`${options.referenceFile}\` (colours, surfaces, the look intents to use as \`refs\`). Building UI does not need it.`, '');
+        return out.join('\n');
+    }
+    out.push(...referenceParts(registry, toolings, options, cli));
+    return out.join('\n');
+}
+/** The reference file: what editing the theme or adding intents needs, and building does not. */
+export function compileReference(registry, toolings, options = {}) {
+    const cli = options.cli ?? 'npx prongs';
+    return [
+        `# ${options.referenceFile ?? 'PRONGS.reference.md'}`,
+        '',
+        `Generated from \`${options.registryPath ?? 'the intent registry'}\` by \`${cli} spec\`. Do not edit by hand. For building UI, read PRONGS.md instead.`,
+        '',
+        ...referenceParts(registry, toolings, options, cli),
+    ].join('\n');
+}
+function referenceParts(registry, toolings, options, cli) {
+    const out = [];
+    for (const tooling of toolings) {
+        const section = tooling.referenceSection?.(registry, { cli, componentsImport: options.componentsImport });
+        if (section)
+            out.push(section.trim(), '');
+    }
+    const look = registry.ids.filter((id) => registry.isInternal(id));
+    if (look.length) {
+        out.push('## Look intents', '');
+        out.push(`Ref-only building blocks. Never use them at call sites; list them in \`refs\` when you add an intent. Their classes are in \`${options.registryPath ?? 'the registry'}\`.`, '');
+        for (const id of look)
+            out.push(`- \`${id}\`: ${registry.defs[id].description}`);
+        out.push('');
+    }
+    return out;
+}

package/dist/engine/types.d.ts

@@ -0,0 +1,109 @@
+import type { Check, Intent } from '../spec.js';
+import type { AnyRegistry } from '../registry.js';
+/** A source file, with `path` relative to the project root using forward slashes. */
+export type SourceFile = {
+    path: string;
+    text: string;
+};
+export type Severity = 'error' | 'warning' | 'info';
+export type Suggestion = {
+    text: string;
+    intent?: string;
+    component?: string;
+    /** A ready-to-run command, e.g. `npx prongs add-intent ...`. */
+    command?: string;
+};
+/** What the spec knows about the project, for tooling that writes its own sections. */
+export type SpecContext = {
+    /** How to run the CLI in this project. */
+    cli: string;
+    /** The import path of the project's components, e.g. `@/components/prongs`. */
+    componentsImport?: string;
+};
+export type Violation = {
+    rule: string;
+    severity: Severity;
+    path: string;
+    line: number;
+    column: number;
+    message: string;
+    /** The source line, trimmed. Used for baselines, so it must not include line numbers. */
+    snippet: string;
+    intent?: string;
+    suggestions: Suggestion[];
+    /** Rule-specific details, e.g. offending classes. Used by --suggest. */
+    data?: Record<string, unknown>;
+};
+/** One place in code where an intent is used. */
+export type Usage = {
+    intent: string;
+    path: string;
+    line: number;
+    column: number;
+    snippet: string;
+    /** What the intent was used through, e.g. a component name. Profile-defined. */
+    via?: string;
+};
+export type ToolingContext = {
+    registry: AnyRegistry;
+    file: SourceFile;
+};
+/** What a rule finds, written for people and agents: the docs' check-rules page reads these. */
+export type RuleDoc = {
+    id: string;
+    /** The profile whose tooling reports it, or `core` for rules every profile shares. */
+    profile: string;
+    severity: Severity;
+    /** What it catches, in a sentence or two. May use `backticks`. */
+    summary: string;
+    /** Code that triggers it, and the fix. */
+    bad?: string;
+    good?: string;
+};
+export type Rule = {
+    id: string;
+    run(ctx: ToolingContext): Violation[];
+};
+/** A rule over the whole project at once, for patterns no single file shows (a tweak repeated across pages). */
+export type ProjectRule = {
+    id: string;
+    run(ctx: {
+        registry: AnyRegistry;
+        files: readonly SourceFile[];
+    }): Violation[];
+};
+export type CheckImpl = (args: {
+    check: Check;
+    intentId: string;
+    intent: Intent;
+    usage: Usage;
+    ctx: ToolingContext;
+}) => Violation[];
+/**
+ * The tooling half of a profile: how its intents show up in code and how to
+ * verify them. Never shipped to the browser.
+ */
+/** The part of a profile's tooling that writes PRONGS.md, usable without the code analysis. */
+export type SpecTooling = Pick<ProfileTooling, 'name' | 'describe' | 'specSection' | 'referenceSection' | 'groupOf' | 'usage'>;
+export type ProfileTooling = {
+    /** Must match the runtime Profile's name. */
+    name: string;
+    appliesTo(path: string): boolean;
+    findUsages(ctx: ToolingContext): Usage[];
+    /** File-level rules, e.g. "no raw <button>". */
+    rules?: Rule[];
+    /** Rules over every file the tooling applies to, run once per check. */
+    projectRules?: ProjectRule[];
+    /** Per-intent check implementations, keyed by Check.type. */
+    checks?: Record<string, CheckImpl>;
+    /** What a resolved binding produces (element, role, type), shown next to the intent in the spec's index. */
+    describe?(binding: unknown): string;
+    /** Extra markdown placed in the spec after the intent index. */
+    specSection?(registry: AnyRegistry, context: SpecContext): string;
+    /** Markdown only needed to change the system (theme, new intents): goes to the reference file when there is one. */
+    referenceSection?(registry: AnyRegistry, context: SpecContext): string;
+    /** Groups call-site intents in the index, e.g. by component. Defaults to domain. */
+    groupOf?(id: string): string;
+    /** One line showing how code uses an intent, for `prongs find`: `<Action intent="action.delete">…</Action>`. */
+    usage?(id: string, binding: unknown): string;
+};

package/dist/engine/types.js

@@ -0,0 +1 @@
+export {};

package/dist/engine/util.d.ts

@@ -0,0 +1,11 @@
+import type { AnyRegistry } from '../registry.js';
+export declare function locate(text: string, offset: number): {
+    line: number;
+    column: number;
+    snippet: string;
+};
+export declare function editDistance(a: string, b: string): number;
+/** Intent ids closest to `query` by spelling, call-site intents only. */
+export declare function nearestIntents(registry: AnyRegistry, query: string, limit?: number): string[];
+/** Call-site intents that reference `id`, directly or through other intents. */
+export declare function intentsUsing(registry: AnyRegistry, id: string): string[];

package/dist/engine/util.js

@@ -0,0 +1,52 @@
+export function locate(text, offset) {
+    let line = 1;
+    let lineStart = 0;
+    for (let i = 0; i < offset && i < text.length; i++) {
+        if (text[i] === '\n') {
+            line++;
+            lineStart = i + 1;
+        }
+    }
+    const lineEnd = text.indexOf('\n', lineStart);
+    const snippet = text.slice(lineStart, lineEnd === -1 ? undefined : lineEnd).trim();
+    return { line, column: offset - lineStart + 1, snippet };
+}
+export function editDistance(a, b) {
+    const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let diag = prev[0];
+        prev[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const temp = prev[j];
+            prev[j] = Math.min(prev[j] + 1, prev[j - 1] + 1, diag + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diag = temp;
+        }
+    }
+    return prev[b.length];
+}
+/** Intent ids closest to `query` by spelling, call-site intents only. */
+export function nearestIntents(registry, query, limit = 3) {
+    return registry.ids
+        .filter((id) => !registry.isInternal(id))
+        .map((id) => ({ id, d: editDistance(query, id) }))
+        .filter(({ id, d }) => d <= Math.max(3, Math.floor(id.length / 3)))
+        .sort((a, b) => a.d - b.d || a.id.localeCompare(b.id))
+        .slice(0, limit)
+        .map(({ id }) => id);
+}
+/** Call-site intents that reference `id`, directly or through other intents. */
+export function intentsUsing(registry, id) {
+    const users = new Set();
+    const visit = (target) => {
+        for (const candidate of registry.ids) {
+            if (users.has(candidate))
+                continue;
+            if ((registry.defs[candidate].refs ?? []).includes(target)) {
+                users.add(candidate);
+                visit(candidate);
+            }
+        }
+    };
+    visit(id);
+    return [...users].filter((u) => !registry.isInternal(u)).sort();
+}

package/dist/export.d.ts

@@ -0,0 +1,18 @@
+import type { AnyRegistry } from './registry.js';
+import type { IntentDefs } from './spec.js';
+/** The version of the Prongs Intent Spec this package implements. */
+export declare const SPEC_VERSION = "draft";
+export type RegistryExport = {
+    spec: string;
+    profiles: {
+        name: string;
+        domains: string[];
+        internalDomains?: string[];
+    }[];
+    intents: IntentDefs;
+};
+/**
+ * A registry as JSON, for tools in other languages (spec §7): the profiles' names and domains,
+ * not their code, and every intent as written. Bindings that hold functions lose them.
+ */
+export declare function exportRegistry(registry: AnyRegistry): RegistryExport;

package/dist/export.js

@@ -0,0 +1,17 @@
+/** The version of the Prongs Intent Spec this package implements. */
+export const SPEC_VERSION = 'draft';
+/**
+ * A registry as JSON, for tools in other languages (spec §7): the profiles' names and domains,
+ * not their code, and every intent as written. Bindings that hold functions lose them.
+ */
+export function exportRegistry(registry) {
+    return {
+        spec: SPEC_VERSION,
+        profiles: registry.profiles.map((p) => ({
+            name: p.name,
+            domains: [...p.domains],
+            ...(p.internalDomains?.length ? { internalDomains: [...p.internalDomains] } : {}),
+        })),
+        intents: JSON.parse(JSON.stringify(registry.defs)),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export type { Check, Intent, IntentDefs, NotFor, IntentKind, IntentStatus, Profile, ProfileIssue, ResolvedIntent, } from './spec.js';
+export { ID_PATTERN, META_KEY_PATTERN, domainOf, isReservedMetaKey } from './spec.js';
+export { createRegistry, RegistryError } from './registry.js';
+export type { AnyRegistry, CreateRegistryOptions, IntentIn, IntentOf, Registry } from './registry.js';
+export { SPEC_VERSION, exportRegistry } from './export.js';
+export type { RegistryExport } from './export.js';
+export { validateRegistry } from './validate.js';
+export type { RegistryIssue, RegistryIssueCode } from './validate.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { ID_PATTERN, META_KEY_PATTERN, domainOf, isReservedMetaKey } from './spec.js';
+export { createRegistry, RegistryError } from './registry.js';
+export { SPEC_VERSION, exportRegistry } from './export.js';
+export { validateRegistry } from './validate.js';

package/dist/registry.d.ts

@@ -0,0 +1,32 @@
+import { type IntentDefs, type Profile, type ResolvedIntent } from './spec.js';
+import { type RegistryIssue } from './validate.js';
+export type Registry<T extends IntentDefs = IntentDefs> = {
+    readonly defs: T;
+    readonly profiles: readonly Profile[];
+    readonly ids: readonly (keyof T & string)[];
+    has(id: string): id is keyof T & string;
+    profileOf(id: string): Profile;
+    /** True when the id belongs to a domain that may only be used as a ref. */
+    isInternal(id: string): boolean;
+    resolve<B = any>(id: keyof T & string): ResolvedIntent<B>;
+};
+/** A registry of any shape; what tooling accepts. */
+export type AnyRegistry = Registry<any>;
+/** Every intent id in a registry, as a literal union. */
+export type IntentOf<R> = R extends Registry<infer T> ? keyof T & string : never;
+/** Intent ids in the given domain(s): IntentIn<typeof registry, 'action'>. */
+export type IntentIn<R, D extends string> = Extract<IntentOf<R>, `${D}.${string}`>;
+export type CreateRegistryOptions = {
+    profiles: readonly Profile[];
+    /** Validate definitions on creation. Defaults to true outside production. */
+    validate?: boolean;
+};
+export declare class RegistryError extends Error {
+    readonly issues: RegistryIssue[];
+    constructor(issues: RegistryIssue[]);
+}
+/**
+ * Wraps plain intent definitions into a typed registry. Pass the object inline
+ * (or `as const`) so intent ids are inferred as literal types.
+ */
+export declare function createRegistry<const T extends IntentDefs>(defs: T, options: CreateRegistryOptions): Registry<T>;

package/dist/registry.js

@@ -0,0 +1,70 @@
+import { domainOf } from './spec.js';
+import { profileForDomain, validateRegistry } from './validate.js';
+export class RegistryError extends Error {
+    issues;
+    constructor(issues) {
+        super(`[prongs] Invalid intent registry:\n${issues.map((i) => `  - ${i.id}: ${i.message}`).join('\n')}`);
+        this.issues = issues;
+        this.name = 'RegistryError';
+    }
+}
+function isDev() {
+    try {
+        return process.env.NODE_ENV !== 'production';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Wraps plain intent definitions into a typed registry. Pass the object inline
+ * (or `as const`) so intent ids are inferred as literal types.
+ */
+export function createRegistry(defs, options) {
+    const { profiles } = options;
+    if (options.validate ?? isDev()) {
+        const errors = validateRegistry(defs, profiles).filter((i) => i.severity === 'error');
+        if (errors.length > 0)
+            throw new RegistryError(errors);
+    }
+    const cache = new Map();
+    const profileOf = (id) => {
+        const profile = profileForDomain(profiles, domainOf(id));
+        if (!profile)
+            throw new Error(`[prongs] No profile owns the "${domainOf(id)}" domain (intent "${id}").`);
+        return profile;
+    };
+    const resolveBinding = (id, visiting) => {
+        const intent = defs[id];
+        if (!intent) {
+            throw new Error(`[prongs] Unknown intent "${id}". See PRONGS.md for the available intents.`);
+        }
+        if (visiting.has(id))
+            throw new Error(`[prongs] Circular intent reference at "${id}".`);
+        visiting.add(id);
+        const profile = profileOf(id);
+        let binding;
+        for (const ref of intent.refs ?? []) {
+            binding = profile.merge(binding, resolveBinding(ref, visiting));
+        }
+        binding = profile.merge(binding, intent.binding);
+        visiting.delete(id);
+        return binding;
+    };
+    return {
+        defs,
+        profiles,
+        ids: Object.keys(defs),
+        has: (id) => Object.prototype.hasOwnProperty.call(defs, id),
+        profileOf,
+        isInternal: (id) => profileOf(id).internalDomains?.includes(domainOf(id)) ?? false,
+        resolve(id) {
+            let resolved = cache.get(id);
+            if (!resolved) {
+                resolved = { id, profile: profileOf(id).name, binding: resolveBinding(id, new Set()) };
+                cache.set(id, resolved);
+            }
+            return resolved;
+        },
+    };
+}

package/dist/spec.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The Prongs intent spec.
+ *
+ * An intent is a named choice inside a codebase: what it is for (so an agent can
+ * pick it), what it resolves to (its binding), when not to use it, and how to
+ * verify it was followed. Core knows nothing about any domain: UI, data access,
+ * routes and so on plug in as profiles that own a set of id prefixes.
+ */
+export type IntentKind = 'primitive' | 'semantic';
+export type IntentStatus = 'stable' | 'beta' | 'experimental' | 'deprecated';
+/** When NOT to use an intent, and what to use instead. Drives selection. */
+export type NotFor = {
+    context: string;
+    reason?: string;
+    instead?: string;
+};
+/** A per-intent check. `type` is defined by the owning profile's tooling. */
+export type Check = {
+    type: string;
+} & Record<string, unknown>;
+export type Intent<B = unknown, C extends Check = Check> = {
+    kind: IntentKind;
+    /** One sentence: what this intent is FOR, not what it looks like. Required. */
+    description: string;
+    /** Semantic intents inherit from these, in order. Same profile only. */
+    refs?: readonly string[];
+    /** What the intent resolves to. Shape owned by the profile. */
+    binding?: B;
+    notFor?: readonly NotFor[];
+    /**
+     * Words in code that point to this intent: handler names, labels, prop names.
+     * e.g. action.bookmark: ['save', 'bookmark']. Tooling uses them to spot an intent
+     * that disagrees with the code it is used in; agents can read them as hints.
+     */
+    keywords?: readonly string[];
+    checks?: readonly C[];
+    status?: IntentStatus;
+    /** Written by tooling (e.g. trial results), never by hand. Shape not yet fixed. */
+    evidence?: Readonly<Record<string, unknown>>;
+    /**
+     * Data the spec does not define, for teams and tools: an owner, a design link, a ticket.
+     * Keys are prefixed, `com.example/owner`, so two tools never claim the same key.
+     */
+    meta?: Readonly<Record<string, unknown>>;
+};
+export type IntentDefs = Record<string, Intent<any, any>>;
+/** A validation finding. Errors make a registry invalid; warnings are reported but allowed. */
+export type ProfileIssue = string | {
+    message: string;
+    severity: 'error' | 'warning';
+};
+/**
+ * A profile defines what a binding means for the domains it owns.
+ * This is the runtime half; it ships with the app, so keep it small.
+ * Tooling (finding usages, rules) lives in a separate ProfileTooling object.
+ */
+export type Profile<B = any> = {
+    name: string;
+    /** Id prefixes this profile owns, e.g. ['action', 'control']. */
+    domains: readonly string[];
+    /** Domains that may only be used as `refs` targets, never at a call site. */
+    internalDomains?: readonly string[];
+    /** Returns problems with one intent's binding or refs. Plain strings are errors. */
+    validate?(id: string, intent: Intent<B>, defs: IntentDefs): ProfileIssue[];
+    /** Rules about the vocabulary as a whole, e.g. "neighbouring intents must contrast". */
+    validateAll?(defs: IntentDefs): {
+        id: string;
+        message: string;
+        severity: 'error' | 'warning';
+    }[];
+    /** Layers `next` over `base`. Must accept undefined for either. */
+    merge(base: B | undefined, next: B | undefined): B;
+};
+export type ResolvedIntent<B = unknown> = {
+    id: string;
+    profile: string;
+    binding: B;
+};
+export declare const ID_PATTERN: RegExp;
+/** A `meta` key: a reverse-DNS prefix and a name, `com.example/owner`. */
+export declare const META_KEY_PATTERN: RegExp;
+/** True for `meta` prefixes the spec keeps for itself: any whose second label is `prongs` (`dev.prongs/`). */
+export declare function isReservedMetaKey(key: string): boolean;
+export declare function domainOf(id: string): string;

package/dist/spec.js

@@ -0,0 +1,18 @@
+/**
+ * The Prongs intent spec.
+ *
+ * An intent is a named choice inside a codebase: what it is for (so an agent can
+ * pick it), what it resolves to (its binding), when not to use it, and how to
+ * verify it was followed. Core knows nothing about any domain: UI, data access,
+ * routes and so on plug in as profiles that own a set of id prefixes.
+ */
+export const ID_PATTERN = /^[a-z]+(\.[a-z]+){1,2}$/;
+/** A `meta` key: a reverse-DNS prefix and a name, `com.example/owner`. */
+export const META_KEY_PATTERN = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+\/[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?$/;
+/** True for `meta` prefixes the spec keeps for itself: any whose second label is `prongs` (`dev.prongs/`). */
+export function isReservedMetaKey(key) {
+    return key.split('/')[0].split('.')[1] === 'prongs';
+}
+export function domainOf(id) {
+    return id.split('.')[0];
+}

package/dist/validate.d.ts

@@ -0,0 +1,18 @@
+import { type IntentDefs, type Profile } from './spec.js';
+/**
+ * What a registry problem is, stable across implementations and wording: the spec's
+ * conformance fixtures compare these, not messages.
+ */
+export type RegistryIssueCode = 'domain-conflict' | 'internal-domain-not-owned' | 'id-grammar' | 'no-profile' | 'description-missing' | 'primitive-refs' | 'semantic-no-refs' | 'unknown-ref' | 'cross-profile-ref' | 'unknown-instead' | 'ref-cycle' | 'meta-key' | 'meta-reserved' | 'deprecated-no-instead' | 'duplicate-keyword' | 'profile';
+export type RegistryIssue = {
+    id: string;
+    message: string;
+    severity: 'error' | 'warning';
+    code: RegistryIssueCode;
+};
+export declare function profileForDomain(profiles: readonly Profile[], domain: string): Profile | undefined;
+/**
+ * Checks a set of intent definitions against the spec and their profiles.
+ * Returns every problem rather than stopping at the first.
+ */
+export declare function validateRegistry(defs: IntentDefs, profiles: readonly Profile[]): RegistryIssue[];

package/dist/validate.js

@@ -0,0 +1,115 @@
+import { ID_PATTERN, META_KEY_PATTERN, domainOf, isReservedMetaKey } from './spec.js';
+export function profileForDomain(profiles, domain) {
+    return profiles.find((p) => p.domains.includes(domain));
+}
+/**
+ * Checks a set of intent definitions against the spec and their profiles.
+ * Returns every problem rather than stopping at the first.
+ */
+export function validateRegistry(defs, profiles) {
+    const issues = [];
+    const add = (code, id, message, severity = 'error') => issues.push({ id, message, severity, code });
+    const seenDomains = new Map();
+    for (const profile of profiles) {
+        for (const domain of profile.domains) {
+            const owner = seenDomains.get(domain);
+            if (owner)
+                add('domain-conflict', domain, `domain "${domain}" is owned by both "${owner}" and "${profile.name}" profiles`);
+            seenDomains.set(domain, profile.name);
+        }
+        for (const domain of profile.internalDomains ?? []) {
+            if (!profile.domains.includes(domain)) {
+                add('internal-domain-not-owned', domain, `profile "${profile.name}" lists internal domain "${domain}" that it does not own`);
+            }
+        }
+    }
+    for (const [id, intent] of Object.entries(defs)) {
+        if (!ID_PATTERN.test(id)) {
+            add('id-grammar', id, 'id must look like domain.meaning or domain.meaning.variant (lowercase letters only)');
+        }
+        const profile = profileForDomain(profiles, domainOf(id));
+        if (!profile) {
+            add('no-profile', id, `no profile owns the "${domainOf(id)}" domain`);
+            continue;
+        }
+        if (!intent.description || !intent.description.trim()) {
+            add('description-missing', id, 'description is required: it is what agents choose intents by');
+        }
+        const refs = intent.refs ?? [];
+        if (intent.kind === 'primitive' && refs.length > 0) {
+            add('primitive-refs', id, 'primitive intents cannot have refs; use kind "semantic"');
+        }
+        if (intent.kind === 'semantic' && refs.length === 0) {
+            add('semantic-no-refs', id, 'semantic intents need at least one ref');
+        }
+        for (const ref of refs) {
+            if (!(ref in defs))
+                add('unknown-ref', id, `refs unknown intent "${ref}"`);
+            else if (profileForDomain(profiles, domainOf(ref)) !== profile) {
+                add('cross-profile-ref', id, `refs "${ref}", which belongs to a different profile`);
+            }
+        }
+        for (const exception of intent.notFor ?? []) {
+            if (exception.instead && !(exception.instead in defs)) {
+                add('unknown-instead', id, `notFor points to unknown intent "${exception.instead}"`);
+            }
+        }
+        if (intent.status === 'deprecated' && !(intent.notFor ?? []).some((e) => e.instead)) {
+            add('deprecated-no-instead', id, 'deprecated, but no notFor says what to use instead', 'warning');
+        }
+        for (const key of Object.keys(intent.meta ?? {})) {
+            if (!META_KEY_PATTERN.test(key)) {
+                add('meta-key', id, `meta key "${key}" needs a reverse-DNS prefix, like "com.example/${key.split('/').pop()}"`);
+            }
+            else if (isReservedMetaKey(key)) {
+                add('meta-reserved', id, `meta key "${key}" uses a prefix the spec reserves, and the spec defines no such key`, 'warning');
+            }
+        }
+        for (const issue of profile.validate?.(id, intent, defs) ?? []) {
+            if (typeof issue === 'string')
+                add('profile', id, issue);
+            else
+                add('profile', id, issue.message, issue.severity);
+        }
+    }
+    for (const profile of profiles) {
+        const owned = Object.fromEntries(Object.entries(defs).filter(([id]) => profileForDomain(profiles, domainOf(id)) === profile));
+        for (const issue of profile.validateAll?.(owned) ?? [])
+            issues.push({ ...issue, code: 'profile' });
+    }
+    // Keywords tell the intents of a domain apart. One claimed twice gives check and agents two answers.
+    const claimed = new Map();
+    for (const [id, intent] of Object.entries(defs)) {
+        for (const keyword of intent.keywords ?? []) {
+            const key = `${domainOf(id)}:${keyword}`;
+            const other = claimed.get(key);
+            if (other)
+                add('duplicate-keyword', id, `keyword "${keyword}" is also on "${other}"; keep it on the one it means`, 'warning');
+            else
+                claimed.set(key, id);
+        }
+    }
+    for (const cycle of findCycles(defs)) {
+        add('ref-cycle', cycle[0], `circular refs: ${cycle.join(' -> ')}`);
+    }
+    return issues;
+}
+function findCycles(defs) {
+    const cycles = [];
+    const state = new Map();
+    const visit = (id, path) => {
+        if (state.get(id) === 'done' || !(id in defs))
+            return;
+        if (state.get(id) === 'visiting') {
+            cycles.push([...path.slice(path.indexOf(id)), id]);
+            return;
+        }
+        state.set(id, 'visiting');
+        for (const ref of defs[id].refs ?? [])
+            visit(ref, [...path, id]);
+        state.set(id, 'done');
+    };
+    for (const id of Object.keys(defs))
+        visit(id, []);
+    return cycles;
+}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@prongsjs/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "The Prongs intent spec: typed intent registries, profiles, and the engine that checks how intents are used.",
+  "keywords": [
+    "intents",
+    "registry",
+    "ai-agents",
+    "design-system",
+    "typescript"
+  ],
+  "homepage": "https://github.com/drewpoling2/prongs#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drewpoling2/prongs.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/drewpoling2/prongs/issues"
+  },
+  "author": "Drew Poling",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./engine": {
+      "types": "./dist/engine/index.d.ts",
+      "import": "./dist/engine/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "test": "vitest run && tsc -p tsconfig.typetest.json",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}