planfs-core 1.3.0 → 1.4.0

package/dist/semantic-analyzer.js

@@ -0,0 +1,315 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalRuleSemanticAnalyzer = exports.LOCAL_RULE_ANALYZER_IDENTITY = void 0;
+exports.runSemanticAnalysis = runSemanticAnalysis;
+exports.LOCAL_RULE_ANALYZER_IDENTITY = Object.freeze({
+    id: 'planfs-local-english-rules',
+    version: '1.0.0'
+});
+const DEFAULT_CACHE_SIZE = 256;
+const SUPPORTED_LANGUAGES = ['en'];
+/**
+ * Local advisory prose analyzer containing only signals promoted by TASK-118.
+ * It never changes the semantic document or authoritative entity metadata.
+ */
+class LocalRuleSemanticAnalyzer {
+    constructor(options = {}) {
+        this.identity = exports.LOCAL_RULE_ANALYZER_IDENTITY;
+        this.supportedLanguages = SUPPORTED_LANGUAGES;
+        this.cache = new Map();
+        this.hits = 0;
+        this.misses = 0;
+        this.evictions = 0;
+        const requestedCapacity = options.cacheSize ?? DEFAULT_CACHE_SIZE;
+        if (!Number.isSafeInteger(requestedCapacity) || requestedCapacity < 0) {
+            throw new Error('cacheSize must be a non-negative safe integer');
+        }
+        this.capacity = requestedCapacity;
+    }
+    get cacheStats() {
+        return {
+            size: this.cache.size,
+            capacity: this.capacity,
+            hits: this.hits,
+            misses: this.misses,
+            evictions: this.evictions
+        };
+    }
+    clearCache() {
+        this.cache.clear();
+    }
+    async analyze(request) {
+        const language = normalizeLanguage(request.language);
+        if (!this.supportedLanguages.includes(language)) {
+            return {
+                analyzer: { ...this.identity },
+                language,
+                signals: [],
+                diagnostics: [unsupportedLanguageDiagnostic(this.identity, language)]
+            };
+        }
+        const key = createCacheKey(request.document, language, this.identity);
+        const cached = this.cache.get(key);
+        if (cached) {
+            this.hits += 1;
+            this.cache.delete(key);
+            this.cache.set(key, cached);
+            return cloneAnalyzerResult(cached.value);
+        }
+        this.misses += 1;
+        const result = {
+            analyzer: { ...this.identity },
+            language,
+            signals: request.document.criteria
+                .flatMap(criterion => analyzeCriterion(request.document, criterion, language))
+                .sort(compareSignals),
+            diagnostics: []
+        };
+        if (this.capacity > 0) {
+            this.cache.set(key, { key, value: cloneAnalyzerResult(result) });
+            if (this.cache.size > this.capacity) {
+                const oldestKey = this.cache.keys().next().value;
+                if (oldestKey !== undefined)
+                    this.cache.delete(oldestKey);
+                this.evictions += 1;
+            }
+        }
+        return cloneAnalyzerResult(result);
+    }
+}
+exports.LocalRuleSemanticAnalyzer = LocalRuleSemanticAnalyzer;
+const defaultAnalyzer = new LocalRuleSemanticAnalyzer();
+/**
+ * Explicit opt-in helper. A disabled request returns null and performs no analysis.
+ * Analyzer failures are converted into bounded advisory diagnostics.
+ */
+async function runSemanticAnalysis(document, options = {}) {
+    if (options.enabled !== true)
+        return null;
+    const analyzer = options.analyzer ?? defaultAnalyzer;
+    const language = normalizeLanguage(options.language ?? 'en');
+    try {
+        return await analyzer.analyze({ document, language });
+    }
+    catch (error) {
+        return {
+            analyzer: { ...analyzer.identity },
+            language,
+            signals: [],
+            diagnostics: [analyzerFailureDiagnostic(analyzer.identity, error)]
+        };
+    }
+}
+function analyzeCriterion(document, criterion, language) {
+    let eligible = maskIneligibleMarkdown(criterion.markdown);
+    for (const child of document.criteria.filter(candidate => candidate.parentCriterionId === criterion.id)) {
+        const start = child.range.start.offset - criterion.range.start.offset;
+        const end = child.range.end.offset - criterion.range.start.offset;
+        eligible = maskRange(eligible, start, end);
+    }
+    const matches = [];
+    collect(matches, eligible, /\b(must|should|may)\b/gi, 'modality', 0.98, 'exact-modal-token');
+    collect(matches, eligible, /\b(not|never|no|without)\b/gi, 'negation', 0.98, 'exact-negation-token');
+    collect(matches, eligible, /\b(if|when|unless|until|after|before|once)\b/gi, 'condition', 0.95, 'bounded-condition-introducer');
+    collect(matches, eligible, /\b(?:\d+(?:\.\d+)?\s*(?:ms|milliseconds?|seconds?|minutes?|hours?|days?)|per second|tomorrow|\d{4}-\d{2}-\d{2})\b/gi, 'date-duration', 0.95, 'explicit-date-or-duration');
+    collectRelationships(matches, eligible);
+    return deduplicateMatches(matches).map(match => toSignal(document, criterion, match, language));
+}
+function collectRelationships(matches, eligible) {
+    const entities = [...eligible.matchAll(/\b(?:TASK-[0-9]{3,}|EPIC-[A-Za-z0-9-]+|MILESTONE-[A-Za-z0-9-]+|DECISION-[A-Za-z0-9-]+)\b/g)];
+    const phrases = [...eligible.matchAll(/\b(?:after|before|block(?:s|ed by)?|depend(?:s|ed)? on|belongs under|parent)\b/gi)];
+    if (entities.length === 0 || phrases.length === 0)
+        return;
+    for (const entity of entities) {
+        const phrase = nearestMatch(entity, phrases);
+        const entityStart = entity.index ?? 0;
+        const phraseStart = phrase.index ?? 0;
+        const entityEnd = entityStart + entity[0].length;
+        const phraseEnd = phraseStart + phrase[0].length;
+        const gapStart = Math.min(entityEnd, phraseEnd);
+        const gapEnd = Math.max(entityStart, phraseStart);
+        const gap = eligible.slice(gapStart, gapEnd);
+        if (gap.length > 80 || /[.!?\n]/.test(gap))
+            continue;
+        matches.push({
+            kind: 'relationship-mention',
+            start: Math.min(entityStart, phraseStart),
+            end: Math.max(entityEnd, phraseEnd),
+            confidence: 0.90,
+            basis: 'exact-planfs-id-with-bounded-relationship-phrase',
+            evidence: [
+                { start: phraseStart, end: phraseEnd },
+                { start: entityStart, end: entityEnd }
+            ],
+            data: {
+                targetId: entity[0],
+                relationshipPhrase: phrase[0].toLowerCase()
+            }
+        });
+    }
+}
+function maskIneligibleMarkdown(markdown) {
+    let value = markdown;
+    const patterns = [
+        /(^|\n)[ \t]*(```+|~~~+)[^\n]*(?:\n[\s\S]*?(?:\n[ \t]*\2[^\n]*)?(?=\n|$)|$)/g,
+        /`+[^`\n]*`+/g,
+        /<!--[\s\S]*?-->/g,
+        /<([A-Za-z][A-Za-z0-9-]*)\b[^>]*>[\s\S]*?<\/\1\s*>/g,
+        /<https?:\/\/[^>]+>/gi,
+        /<[^>]*>/g,
+        /\]\([^)]*\)/g,
+        /https?:\/\/[^\s)>]+/gi,
+        /(^|\n)[ \t]*(?:[-+*]|\d+[.)])[ \t]+(?:\[[ xX]\][ \t]+)?/g
+    ];
+    for (const pattern of patterns) {
+        value = value.replace(pattern, matched => ' '.repeat(matched.length));
+    }
+    return value.replace(/[_*~>#]/g, ' ').replace(/\[/g, ' ').replace(/\]/g, ' ');
+}
+function maskRange(value, start, end) {
+    const safeStart = Math.max(0, Math.min(value.length, start));
+    const safeEnd = Math.max(safeStart, Math.min(value.length, end));
+    return `${value.slice(0, safeStart)}${' '.repeat(safeEnd - safeStart)}${value.slice(safeEnd)}`;
+}
+function collect(target, text, pattern, kind, confidence, basis) {
+    for (const match of text.matchAll(pattern)) {
+        const start = match.index ?? 0;
+        target.push({
+            kind,
+            start,
+            end: start + match[0].length,
+            confidence,
+            basis,
+            evidence: [{ start, end: start + match[0].length }]
+        });
+    }
+}
+function nearestMatch(target, matches) {
+    const targetIndex = target.index ?? 0;
+    return matches.reduce((nearest, candidate) => (Math.abs((candidate.index ?? 0) - targetIndex) < Math.abs((nearest.index ?? 0) - targetIndex)
+        ? candidate
+        : nearest));
+}
+function deduplicateMatches(matches) {
+    const seen = new Set();
+    return matches.filter(match => {
+        const key = `${match.kind}:${match.start}:${match.end}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function toSignal(document, criterion, match, language) {
+    const criterionStart = criterion.range.start.offset;
+    const range = sourceRange(document.source.rawMarkdown, criterionStart + match.start, criterionStart + match.end);
+    const evidence = match.evidence.map(item => {
+        const evidenceRange = sourceRange(document.source.rawMarkdown, criterionStart + item.start, criterionStart + item.end);
+        return {
+            text: document.source.rawMarkdown.slice(evidenceRange.start.offset, evidenceRange.end.offset),
+            range: evidenceRange
+        };
+    });
+    return {
+        kind: match.kind,
+        message: messageFor(match.kind, evidence.map(item => item.text)),
+        language,
+        analyzer: { ...exports.LOCAL_RULE_ANALYZER_IDENTITY },
+        provenance: 'nlp-inferred',
+        range,
+        evidence,
+        confidence: match.confidence,
+        authoritative: false,
+        data: {
+            criterionId: criterion.id,
+            evidenceBasis: match.basis,
+            ...match.data
+        }
+    };
+}
+function messageFor(kind, evidence) {
+    switch (kind) {
+        case 'modality':
+            return `Modal wording detected: ${evidence[0] ?? ''}`;
+        case 'negation':
+            return `Negation detected: ${evidence[0] ?? ''}`;
+        case 'condition':
+            return `Conditional wording detected: ${evidence[0] ?? ''}`;
+        case 'date-duration':
+            return `Date or duration wording detected: ${evidence[0] ?? ''}`;
+        case 'relationship-mention':
+            return `Possible planning relationship mentioned in prose: ${evidence[1] ?? evidence[0] ?? ''}`;
+    }
+}
+function sourceRange(source, start, end) {
+    return { start: sourcePoint(source, start), end: sourcePoint(source, end) };
+}
+function sourcePoint(source, offset) {
+    const before = source.slice(0, offset);
+    const lastNewline = before.lastIndexOf('\n');
+    let line = 1;
+    for (let index = 0; index < before.length; index += 1) {
+        if (before.charCodeAt(index) === 10)
+            line += 1;
+    }
+    return {
+        offset,
+        line,
+        column: offset - lastNewline
+    };
+}
+function compareSignals(left, right) {
+    return left.range.start.offset - right.range.start.offset || left.kind.localeCompare(right.kind);
+}
+function createCacheKey(document, language, identity) {
+    return [
+        identity.id,
+        identity.version,
+        language,
+        document.profile.entityType,
+        document.profile.version,
+        document.source.rawMarkdown
+    ].join('\0');
+}
+function normalizeLanguage(language) {
+    return language.trim().toLowerCase().split('-')[0] ?? '';
+}
+function unsupportedLanguageDiagnostic(identity, language) {
+    return {
+        code: 'analysis.language.unsupported',
+        severity: 'info',
+        message: `Analyzer ${identity.id} does not support language: ${language || '(empty)'}`,
+        range: null,
+        sectionIndex: null,
+        provenance: 'nlp-inferred',
+        conformance: 'analysis',
+        repair: {
+            summary: 'Disable advisory analysis or select a supported language',
+            kind: 'none',
+            previewable: false
+        },
+        data: { language }
+    };
+}
+function analyzerFailureDiagnostic(identity, error) {
+    const errorName = error instanceof Error && error.name ? error.name : 'Error';
+    return {
+        code: 'analysis.analyzer.unavailable',
+        severity: 'warning',
+        message: `Advisory analyzer ${identity.id} could not run locally.`,
+        range: null,
+        sectionIndex: null,
+        provenance: 'nlp-inferred',
+        conformance: 'analysis',
+        repair: {
+            summary: 'Retry without advisory analysis or check the local analyzer configuration',
+            kind: 'none',
+            previewable: false
+        },
+        data: { analyzerId: identity.id, analyzerVersion: identity.version, errorName }
+    };
+}
+function cloneAnalyzerResult(result) {
+    return JSON.parse(JSON.stringify(result));
+}
+//# sourceMappingURL=semantic-analyzer.js.map

package/dist/semantic-analyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-analyzer.js","sourceRoot":"","sources":["../src/semantic-analyzer.ts"],"names":[],"mappings":"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"}

package/dist/semantic-context.d.ts

@@ -0,0 +1,67 @@
+/** Compact semantic planning context shared by agent and human workflows. */
+import { TaskReadinessResult } from './next-work';
+import { SemanticAdvisoryConclusion, SemanticInspectionOptions } from './semantic-inspection';
+import { EntityMention, AnalyzerResult, SemanticCriterion, SemanticDecisionStatement, SemanticDiagnostic, SemanticFinding, SemanticQuestion, SemanticReference, SemanticProvenance, SourceRange } from './semantic-types';
+import { Entity, Repository } from './types';
+export type SemanticPlanningContextVersion = '1.0.0';
+export type SemanticPlanningContextOptions = SemanticInspectionOptions;
+export interface PlanningContextEntity {
+    id: string;
+    type: Entity['type'];
+    title: string;
+    status: Entity['status'];
+    filePath: string;
+    archived: boolean;
+}
+export interface PlanningContextText {
+    heading: string;
+    text: string;
+    markdown: string;
+    provenance: Exclude<SemanticProvenance, 'nlp-inferred'>;
+    range: SourceRange;
+}
+export interface PlanningContextReference {
+    id: string;
+    entity: PlanningContextEntity | null;
+    authoritative: true;
+}
+export interface PlanningContextRelationships {
+    dependsOn: PlanningContextReference[];
+    epic: PlanningContextReference | null;
+    milestone: PlanningContextReference | null;
+    supersedes: PlanningContextReference | null;
+    supersededBy: PlanningContextReference | null;
+}
+export interface PlanningContextReadiness extends TaskReadinessResult {
+    reasons: string[];
+}
+export interface SemanticPlanningContext {
+    contextVersion: SemanticPlanningContextVersion;
+    entity: PlanningContextEntity;
+    intent: {
+        text: string;
+        markdown: string;
+        range: SourceRange;
+    };
+    sections: Record<string, PlanningContextText[]>;
+    acceptanceCriteria: SemanticCriterion[];
+    findings: SemanticFinding[];
+    decisions: SemanticDecisionStatement[];
+    questions: SemanticQuestion[];
+    references: SemanticReference[];
+    relationships: PlanningContextRelationships;
+    readiness: PlanningContextReadiness | null;
+    advisory: {
+        enabled: boolean;
+        mentions: EntityMention[];
+        conclusions: SemanticAdvisoryConclusion[];
+        analysis: AnalyzerResult | null;
+    };
+    diagnostics: SemanticDiagnostic[];
+}
+/**
+ * Project one entity into bounded, traceable planning context. Frontmatter
+ * relationships remain authoritative; body interpretation stays read-only.
+ */
+export declare function buildSemanticPlanningContext(repository: Repository, entityId: string, options?: SemanticPlanningContextOptions): Promise<SemanticPlanningContext>;
+//# sourceMappingURL=semantic-context.d.ts.map

package/dist/semantic-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-context.d.ts","sourceRoot":"","sources":["../src/semantic-context.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAE7E,OAAO,EAAqC,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAErF,OAAO,EAEL,0BAA0B,EAC1B,yBAAyB,EAC1B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,yBAAyB,EACzB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,MAAM,EAAE,UAAU,EAAQ,MAAM,SAAS,CAAC;AAEnD,MAAM,MAAM,8BAA8B,GAAG,OAAO,CAAC;AAErD,MAAM,MAAM,8BAA8B,GAAG,yBAAyB,CAAC;AAEvE,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC,kBAAkB,EAAE,cAAc,CAAC,CAAC;IACxD,KAAK,EAAE,WAAW,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACrC,aAAa,EAAE,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,4BAA4B;IAC3C,SAAS,EAAE,wBAAwB,EAAE,CAAC;IACtC,IAAI,EAAE,wBAAwB,GAAG,IAAI,CAAC;IACtC,SAAS,EAAE,wBAAwB,GAAG,IAAI,CAAC;IAC3C,UAAU,EAAE,wBAAwB,GAAG,IAAI,CAAC;IAC5C,YAAY,EAAE,wBAAwB,GAAG,IAAI,CAAC;CAC/C;AAED,MAAM,WAAW,wBAAyB,SAAQ,mBAAmB;IACnE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,uBAAuB;IACtC,cAAc,EAAE,8BAA8B,CAAC;IAC/C,MAAM,EAAE,qBAAqB,CAAC;IAC9B,MAAM,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,WAAW,CAAC;KACpB,CAAC;IACF,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,EAAE,CAAC,CAAC;IAChD,kBAAkB,EAAE,iBAAiB,EAAE,CAAC;IACxC,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,SAAS,EAAE,yBAAyB,EAAE,CAAC;IACvC,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,UAAU,EAAE,iBAAiB,EAAE,CAAC;IAChC,aAAa,EAAE,4BAA4B,CAAC;IAC5C,SAAS,EAAE,wBAAwB,GAAG,IAAI,CAAC;IAC3C,QAAQ,EAAE;QACR,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,aAAa,EAAE,CAAC;QAC1B,WAAW,EAAE,0BAA0B,EAAE,CAAC;QAC1C,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;KACjC,CAAC;IACF,WAAW,EAAE,kBAAkB,EAAE,CAAC;CACnC;AAED;;;GAGG;AACH,wBAAsB,4BAA4B,CAChD,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,8BAAmC,GAC3C,OAAO,CAAC,uBAAuB,CAAC,CAgElC"}

package/dist/semantic-context.js

@@ -0,0 +1,109 @@
+"use strict";
+/** Compact semantic planning context shared by agent and human workflows. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSemanticPlanningContext = buildSemanticPlanningContext;
+const next_work_1 = require("./next-work");
+const repository_1 = require("./repository");
+const semantic_inspection_1 = require("./semantic-inspection");
+/**
+ * Project one entity into bounded, traceable planning context. Frontmatter
+ * relationships remain authoritative; body interpretation stays read-only.
+ */
+async function buildSemanticPlanningContext(repository, entityId, options = {}) {
+    const entities = (0, repository_1.getAllEntities)(repository, { includeArchived: true });
+    const entity = entities.find(candidate => candidate.id === entityId);
+    if (!entity) {
+        throw new Error(`Entity not found: ${entityId}`);
+    }
+    const inspection = await (0, semantic_inspection_1.inspectSemanticEntity)(entity, {
+        tier: options.tier ?? 'automation-ready',
+        lifecycle: options.lifecycle,
+        criterionCheckState: options.criterionCheckState,
+        analysis: options.analysis === true,
+        language: options.language,
+        analyzer: options.analyzer
+    });
+    const entityIndex = new Map(entities.map(candidate => [candidate.id, candidate]));
+    const relationship = (id) => {
+        if (!id)
+            return null;
+        const resolved = entityIndex.get(id);
+        return {
+            id,
+            entity: resolved ? toContextEntity(resolved) : null,
+            authoritative: true
+        };
+    };
+    const requiredRelationship = (id) => {
+        const resolved = relationship(id);
+        if (!resolved)
+            throw new Error('Relationship ID must not be empty');
+        return resolved;
+    };
+    const readiness = entity.type === 'task'
+        ? taskReadiness(entity, repository)
+        : null;
+    return {
+        contextVersion: '1.0.0',
+        entity: toContextEntity(entity),
+        intent: {
+            text: inspection.semantic.preamble.text,
+            markdown: inspection.semantic.preamble.markdown,
+            range: inspection.semantic.preamble.range
+        },
+        sections: compactSections(inspection.semantic.sections),
+        acceptanceCriteria: inspection.semantic.criteria,
+        findings: inspection.semantic.findings,
+        decisions: inspection.semantic.decisions,
+        questions: inspection.semantic.questions,
+        references: inspection.semantic.references,
+        relationships: {
+            dependsOn: inspection.authoritative.relationships.dependsOn.map(requiredRelationship),
+            epic: relationship(inspection.authoritative.relationships.epic),
+            milestone: relationship(inspection.authoritative.relationships.milestone),
+            supersedes: relationship(inspection.authoritative.relationships.supersedes),
+            supersededBy: relationship(inspection.authoritative.relationships.supersededBy)
+        },
+        readiness,
+        advisory: {
+            enabled: inspection.analysis !== null,
+            mentions: inspection.advisory.mentions,
+            conclusions: inspection.advisory.conclusions,
+            analysis: inspection.analysis
+        },
+        diagnostics: inspection.diagnostics
+    };
+}
+function compactSections(sections) {
+    var _a;
+    const result = {};
+    for (const section of sections) {
+        if (!section.key)
+            continue;
+        (result[_a = section.key] ?? (result[_a] = [])).push({
+            heading: section.heading,
+            text: section.text,
+            markdown: section.contentMarkdown,
+            provenance: section.provenance,
+            range: section.contentRange
+        });
+    }
+    return result;
+}
+function taskReadiness(task, repository) {
+    return {
+        ...(0, next_work_1.getTaskReadiness)(task, repository),
+        reasons: (0, next_work_1.explainNextWork)(task, repository)
+    };
+}
+function toContextEntity(entity) {
+    return {
+        id: entity.id,
+        type: entity.type,
+        title: entity.title,
+        status: entity.status,
+        filePath: entity.filePath,
+        archived: Boolean(entity.archive)
+    };
+}
+//# sourceMappingURL=semantic-context.js.map

package/dist/semantic-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-context.js","sourceRoot":"","sources":["../src/semantic-context.ts"],"names":[],"mappings":"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"}

package/dist/semantic-formatter.d.ts

@@ -0,0 +1,52 @@
+import { SourceRange } from './semantic-types';
+import { Entity } from './types';
+export declare const SEMANTIC_FORMAT_VERSION: "1.0.0";
+export type SemanticFormatEditKind = 'canonicalize-heading' | 'canonicalize-task-marker' | 'add-task-marker';
+export interface SemanticFormatEdit {
+    kind: SemanticFormatEditKind;
+    sectionKey: string;
+    range: SourceRange;
+    before: string;
+    after: string;
+}
+export interface SemanticFormatIssue {
+    code: string;
+    severity: 'info' | 'warning' | 'error';
+    message: string;
+    sectionKey: string | null;
+    range: SourceRange | null;
+    blocksApply: boolean;
+}
+export interface SemanticFormatEntityPreview {
+    formatVersion: typeof SEMANTIC_FORMAT_VERSION;
+    entityId: string;
+    entityType: Entity['type'];
+    filePath: string;
+    sourceFingerprint: string;
+    changed: boolean;
+    blocked: boolean;
+    edits: SemanticFormatEdit[];
+    issues: SemanticFormatIssue[];
+    diff: string;
+    formattedContent: string;
+}
+export interface SemanticFormatBatchPreview {
+    formatVersion: typeof SEMANTIC_FORMAT_VERSION;
+    entityIds: string[];
+    changedEntityIds: string[];
+    blockedEntityIds: string[];
+    expectedFingerprints: Record<string, string>;
+    previews: SemanticFormatEntityPreview[];
+}
+export interface SemanticFormatApplyResult extends SemanticFormatBatchPreview {
+    appliedEntityIds: string[];
+}
+/** Preview deterministic Markdown-only normalization for a bounded entity list. */
+export declare function previewSemanticFormats(rootPath: string, entityIds: readonly string[]): Promise<SemanticFormatBatchPreview>;
+/**
+ * Apply exactly the previously previewed source snapshots. Every proposed
+ * result is validated before the first bounded write occurs.
+ */
+export declare function applySemanticFormats(rootPath: string, entityIds: readonly string[], expectedFingerprints: Readonly<Record<string, string>>): Promise<SemanticFormatApplyResult>;
+export declare function previewSemanticEntityFormat(entity: Entity, sourceContent: string, rootPath?: string): SemanticFormatEntityPreview;
+//# sourceMappingURL=semantic-formatter.d.ts.map

package/dist/semantic-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-formatter.d.ts","sourceRoot":"","sources":["../src/semantic-formatter.ts"],"names":[],"mappings":"AAMA,OAAO,EAAkB,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/D,OAAO,EAAE,MAAM,EAAc,MAAM,SAAS,CAAC;AAE7C,eAAO,MAAM,uBAAuB,EAAG,OAAgB,CAAC;AAExD,MAAM,MAAM,sBAAsB,GAC9B,sBAAsB,GACtB,0BAA0B,GAC1B,iBAAiB,CAAC;AAEtB,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,WAAW,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,2BAA2B;IAC1C,aAAa,EAAE,OAAO,uBAAuB,CAAC;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,0BAA0B;IACzC,aAAa,EAAE,OAAO,uBAAuB,CAAC;IAC9C,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,QAAQ,EAAE,2BAA2B,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,yBAA0B,SAAQ,0BAA0B;IAC3E,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAOD,mFAAmF;AACnF,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,0BAA0B,CAAC,CAOrC;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACrD,OAAO,CAAC,yBAAyB,CAAC,CA2DpC;AAED,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,QAAQ,SAAK,GACZ,2BAA2B,CA6H7B"}