explico 0.1.0

package/src/reference/prose.ts

@@ -0,0 +1,21 @@
+/**
+ * Under-specification safeguard for notation `meaning` prose (Phase C1b).
+ *
+ * A page-local symbol must not get a glossary-style panel for a throwaway
+ * definition, so `meaning` has to be real prose: at least four words and not a
+ * placeholder phrase. Used by the content schema (`src/content.config.ts`) and
+ * the loader so a bad entry fails both `astro check` and `validate:content`.
+ */
+
+/** Placeholder phrases that do not count as a substantive `meaning`. */
+export const PLACEHOLDER_PROSE =
+  /^(?:a\s+(?:variable|value|quantity|constant|parameter|symbol)|tbd|todo|fixme|see\s+above|as\s+above|placeholder|n\/a)\.?$/i;
+
+/** Minimum words for a `meaning` to read as a definition rather than a label. */
+export const MEANING_MIN_WORDS = 4;
+
+export function isSubstantiveMeaning(value: string): boolean {
+  const trimmed = value.trim();
+  if (PLACEHOLDER_PROSE.test(trimmed)) return false;
+  return trimmed.split(/\s+/).filter(Boolean).length >= MEANING_MIN_WORDS;
+}

package/src/reference/references.ts

@@ -0,0 +1,82 @@
+import type {
+  NotationDefinitionScope,
+  NotationDiagnostic,
+  SourceSpan,
+} from './types';
+
+export const NOTATION_KEY_PATTERN = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
+
+export function isNotationKey(value: string): boolean {
+  return NOTATION_KEY_PATTERN.test(value);
+}
+
+export function sharedDefinitionId(key: string): string {
+  return `shared:${key}`;
+}
+
+export function localDefinitionId(lessonId: string, key: string): string {
+  return `page:${lessonId}:${key}`;
+}
+
+export function definitionId(
+  scope: NotationDefinitionScope,
+  key: string,
+): string {
+  return scope.kind === 'shared'
+    ? sharedDefinitionId(key)
+    : localDefinitionId(scope.lessonId, key);
+}
+
+/**
+ * Resolve by lexical scope. Page content and page-local definition bodies see
+ * local definitions first, then shared definitions. Shared definition bodies
+ * can only see shared definitions, so their meaning cannot change by caller.
+ */
+export function resolveReferenceId(
+  key: string,
+  scope: NotationDefinitionScope,
+  availableDefinitionIds: ReadonlySet<string>,
+): string | undefined {
+  if (scope.kind === 'page') {
+    const localId = localDefinitionId(scope.lessonId, key);
+    if (availableDefinitionIds.has(localId)) return localId;
+  }
+
+  const sharedId = sharedDefinitionId(key);
+  return availableDefinitionIds.has(sharedId) ? sharedId : undefined;
+}
+
+export function compareSourceSpans(
+  left: SourceSpan | undefined,
+  right: SourceSpan | undefined,
+): number {
+  if (left === undefined) return right === undefined ? 0 : 1;
+  if (right === undefined) return -1;
+
+  return (
+    left.file.localeCompare(right.file) ||
+    (left.line ?? 0) - (right.line ?? 0) ||
+    (left.column ?? 0) - (right.column ?? 0) ||
+    (left.endLine ?? 0) - (right.endLine ?? 0) ||
+    (left.endColumn ?? 0) - (right.endColumn ?? 0)
+  );
+}
+
+export function compareDiagnostics(
+  left: NotationDiagnostic,
+  right: NotationDiagnostic,
+): number {
+  return (
+    severityRank(left.severity) - severityRank(right.severity) ||
+    left.code.localeCompare(right.code) ||
+    (left.lessonId ?? '').localeCompare(right.lessonId ?? '') ||
+    (left.key ?? '').localeCompare(right.key ?? '') ||
+    (left.definitionId ?? '').localeCompare(right.definitionId ?? '') ||
+    compareSourceSpans(left.source, right.source) ||
+    left.message.localeCompare(right.message)
+  );
+}
+
+function severityRank(severity: NotationDiagnostic['severity']): number {
+  return severity === 'error' ? 0 : 1;
+}