@purview-dev/astroc4 1.0.0-prerelease.2 → 1.0.0-prerelease.4

package/src/grammar/textmate.mjs

@@ -1,439 +0,0 @@
-// textmate.mjs
-// path: src/grammar/textmate.mjs
-// Builds the Shiki / TextMate grammar for LikeC4 out of the vocabulary read
-// from the live Langium grammar (./langium.mjs).
-//
-// Two layers:
-//   - generated — every word list: blocks, keywords, property names and closed
-//     value domains. These are exactly the lists that go stale when the
-//     language grows (`agent` was added to `ElementShape` after v1.59.4).
-//   - structural — how LikeC4 source is *shaped* rather than which words it
-//     uses: comments, quoted and triple-quoted strings, `#tag` vs `#hex`,
-//     `tech:astro` icons, `-[https]->` arrows, `element system` declarations.
-//     These are curated here because a Langium rule does not say how a token
-//     should look, only that it is one.
-//
-// The result must stay plain JSON: Expressive Code JSON-round-trips integration
-// options before the `<Code>` component renders them, and throws on functions
-// or RegExp instances.
-
-/** Scope name of the grammar, as upstream's VS Code extension uses it. */
-export const SCOPE_NAME = 'source.likec4';
-
-/** Shiki language id, plus the short alias used by ` ```c4 ` fences. */
-export const LANGUAGE_NAME = 'likec4';
-export const LANGUAGE_ALIASES = ['c4'];
-
-const TMLANGUAGE_SCHEMA =
-	'https://raw.githubusercontent.com/martinring/tmlanguage/master/tmlanguage.json';
-
-/**
- * Closed value domains: they colour as values, not as keywords.
- * Anything the grammar adds under these names is picked up automatically.
- */
-const VALUE_DOMAINS = [
-	'BorderStyleValue',
-	'DynamicViewDisplayVariantValue',
-	'EdgeRoutingValue',
-	'ElementShape',
-	'IconPositionValue',
-	'LineOptions',
-	'ArrowType',
-	'RankValue',
-	'SizeValue',
-	'SizingValue',
-	'ThemeColor',
-	'ViewLayoutDirection',
-];
-
-/** Control-flow keywords read as keywords, not as a value domain. */
-const KEYWORD_DOMAINS = ['DynamicViewFlowKeyword'];
-
-/** `source` / `target` are the only value-like variables. */
-const VARIABLE_DOMAINS = ['Participant'];
-
-/** Operators whose scope is a word, kept curated: they are not all literals. */
-const OPERATOR_WORDS = ['and', 'or', 'not', 'is'];
-
-/** Used when the grammar cannot be read — never expected, never silent. */
-const FALLBACK_ICON_PACKS = ['aws', 'azure', 'bootstrap', 'gcp', 'tech'];
-
-/**
- * @typedef {object} TmPattern
- * @property {string} [name]
- * @property {string} [comment]
- * @property {string} [include]
- * @property {string} [match]
- * @property {string} [begin]
- * @property {string} [end]
- * @property {string} [contentName]
- * @property {Record<string, { name: string }>} [captures]
- * @property {Record<string, { name: string }>} [beginCaptures]
- * @property {Record<string, { name: string }>} [endCaptures]
- * @property {TmPattern[]} [patterns]
- */
-
-/**
- * A TextMate grammar: JSON all the way down, never a `RegExp`.
- * @typedef {object} TmGrammar
- * @property {string} $schema
- * @property {string} name
- * @property {string} displayName
- * @property {string} scopeName
- * @property {string[]} fileTypes
- * @property {TmPattern[]} patterns
- * @property {Record<string, any>} repository
- * @property {{ repo: string, ref: string, sha?: string, by: string }} [$generated]
- */
-
-/**
- * @param {import('./langium.mjs').Vocabulary} vocabulary
- * @param {{ repo?: string, ref?: string, sha?: string }} [meta] Provenance.
- * @returns {TmGrammar} A TextMate grammar, JSON-serialisable.
- */
-export function buildTmLanguage(vocabulary, meta = {}) {
-	const control = uniqueDomain(vocabulary, KEYWORD_DOMAINS);
-	const variables = uniqueDomain(vocabulary, VARIABLE_DOMAINS);
-	const icons = vocabulary.icons.length > 0 ? vocabulary.icons : FALLBACK_ICON_PACKS;
-
-	// Words that are always syntax, never the name of a kind: `deployed =
-	// instanceOf a` must not paint `instanceOf` as a type.
-	const reserved = alternationOf([...vocabulary.keywords, ...vocabulary.blocks, ...control]);
-
-	/** @type {TmGrammar} */
-	const grammar = {
-		$schema: TMLANGUAGE_SCHEMA,
-		...(meta.repo && meta.ref
-			? {
-					$generated: {
-						repo: meta.repo,
-						ref: meta.ref,
-						...(meta.sha ? { sha: meta.sha } : {}),
-						by: 'astroc4/scripts/sync-grammar.mjs',
-					},
-				}
-			: {}),
-		name: LANGUAGE_NAME,
-		displayName: 'LikeC4',
-		scopeName: SCOPE_NAME,
-		fileTypes: ['c4', 'likec4'],
-		patterns: [{ include: '#everything' }],
-		repository: {
-			everything: {
-				patterns: [
-					'comments',
-					'strings',
-					'urls',
-					'icons',
-					'hex-colors',
-					'tags',
-					'typed-arrow',
-					'declarations',
-					'keywords',
-					'numbers',
-					'operators',
-					'punctuation',
-				].map((name) => ({ include: `#${name}` })),
-			},
-			comments: comments(),
-			strings: strings(),
-			urls: urls(),
-			icons: iconIds(icons),
-			'hex-colors': hexColours(),
-			tags: tags(),
-			'typed-arrow': typedArrow(),
-			declarations: declarations(reserved),
-			keywords: keywords({ ...vocabulary, control, variables }),
-			numbers: numbers(),
-			operators: operators(vocabulary.arrows),
-			punctuation: punctuation(),
-		},
-	};
-
-	if (meta.repo && meta.ref) {
-		grammar.$generated = {
-			repo: meta.repo,
-			ref: meta.ref,
-			...(meta.sha ? { sha: meta.sha } : {}),
-			by: 'astroc4/scripts/sync-grammar.mjs',
-		};
-	}
-
-	return grammar;
-}
-// region structural patterns
-
-function comments() {
-	return {
-		patterns: [
-			{
-				name: 'comment.block.likec4',
-				begin: '/\\*',
-				end: '\\*/',
-				captures: { 0: { name: 'punctuation.definition.comment.likec4' } },
-			},
-			{
-				name: 'comment.line.double-slash.likec4',
-				match: '//.*$',
-				captures: { 0: { name: 'punctuation.definition.comment.likec4' } },
-			},
-		],
-	};
-}
-
-/**
- * `'…'`, `"…"`, and the markdown strings `''' … '''` / `""" … """` that
- * LikeC4 uses for descriptions.
- */
-function strings() {
-	const triple = (quote) => ({
-		name: 'string.quoted.triple.likec4',
-		begin: quote.repeat(3),
-		end: quote.repeat(3),
-		beginCaptures: { 0: { name: 'punctuation.definition.string.begin.likec4' } },
-		endCaptures: { 0: { name: 'punctuation.definition.string.end.likec4' } },
-	});
-
-	const single = (quote, name) => ({
-		name,
-		begin: quote,
-		end: `${quote}|$`,
-		beginCaptures: { 0: { name: 'punctuation.definition.string.begin.likec4' } },
-		endCaptures: { 0: { name: 'punctuation.definition.string.end.likec4' } },
-		patterns: [{ name: 'constant.character.escape.likec4', match: '\\\\.' }],
-	});
-
-	return {
-		patterns: [
-			triple("'"),
-			triple('"'),
-			single("'", 'string.quoted.single.likec4'),
-			single('"', 'string.quoted.double.likec4'),
-		],
-	};
-}
-
-function urls() {
-	return { name: 'markup.underline.link.likec4', match: "\\bhttps?://[^\\s'\"]+" };
-}
-
-/**
- * Icon ids (`tech:astro`, `aws:lambda`). The packs come from the `LIB_ICON`
- * terminal, so a pack added upstream highlights without touching this package.
- * @param {string[]} packs
- */
-function iconIds(packs) {
-	return {
-		comment: 'Bundled icon ids: `tech:nginx`, `aws:…`, `gcp:…`, …',
-		match: `\\b(${alternationOf(packs)})(:)([\\w-]+)`,
-		captures: {
-			1: { name: 'support.constant.icon-pack.likec4' },
-			2: { name: 'punctuation.separator.likec4' },
-			3: { name: 'support.constant.icon.likec4' },
-		},
-	};
-}
-
-/** `#0046BE` is a colour, `#compute` is a tag — hex first, so it wins. */
-function hexColours() {
-	return {
-		name: 'constant.other.color.rgb-value.hex.likec4',
-		match: '#(?:[0-9A-Fa-f]{8}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{3})(?![\\w-])',
-	};
-}
-
-function tags() {
-	return { name: 'entity.name.tag.likec4', match: '#[A-Za-z_][\\w-]*' };
-}
-
-/** `a -[https]-> b` — the relationship kind inside the connector. */
-function typedArrow() {
-	return {
-		comment: '`a -[https]-> b`',
-		match: '(-\\[)\\s*([A-Za-z_][\\w-]*)\\s*(\\]->)',
-		captures: {
-			1: { name: 'keyword.operator.arrow.likec4' },
-			2: { name: 'entity.name.type.relationship.likec4' },
-			3: { name: 'keyword.operator.arrow.likec4' },
-		},
-	};
-}
-
-/**
- * Declarations: the name being introduced is scoped, the name only being
- * referred to is not. Runs before the keyword patterns so `element system`
- * reads as a declaration rather than as two keywords.
- *
- * @param {string} reserved Alternation of syntax words (`instanceOf`, `extend`,
- *   …), so `deployed = instanceOf a` scopes `instanceOf` as a keyword rather
- *   than as the element kind the name is being assigned.
- */
-function declarations(reserved) {
-	const notReserved = reserved ? `(?!(?:${reserved})\\b)` : '';
-
-	return {
-		patterns: [
-			{
-				comment:
-					'`element system`, `deploymentNode region`, `tag tls`, `relationship https`. Not `where tag is #x`.',
-				match: '\\b(element|deploymentNode|tag|relationship)\\s+(?!is\\b)([A-Za-z_][\\w-]*)(?=\\s*(?:\\{|$|//))',
-				captures: {
-					1: { name: 'storage.type.likec4' },
-					2: { name: 'entity.name.type.likec4' },
-				},
-			},
-			{
-				comment:
-					'`color testingBlue #0046BE` declares; `color testingBlue` inside a style block only refers.',
-				match: '\\b(color)\\s+([A-Za-z_][\\w-]*)(?=\\s+#)',
-				captures: {
-					1: { name: 'storage.type.likec4' },
-					2: { name: 'entity.name.type.likec4' },
-				},
-			},
-			{
-				comment: '`view index`, `dynamic view firstRequest`, `deployment view prod`, `view internals of site`',
-				match: '\\b(?:(dynamic|deployment)\\s+)?(view)\\s+([A-Za-z_]\\w*)',
-				captures: {
-					1: { name: 'storage.modifier.likec4' },
-					2: { name: 'storage.type.view.likec4' },
-					3: { name: 'entity.name.function.view.likec4' },
-				},
-			},
-			{
-				comment: "`reader = actor 'Engineer'`",
-				match: `\\b([A-Za-z_]\\w*)\\s*(=)(?!=)\\s*${notReserved}([A-Za-z_]\\w*)?`,
-				captures: {
-					1: { name: 'variable.other.definition.likec4' },
-					2: { name: 'keyword.operator.assignment.likec4' },
-					3: { name: 'entity.name.type.likec4' },
-				},
-			},
-		],
-	};
-}
-
-// endregion
-
-// region generated keyword patterns
-
-/**
- * Order matters here: blocks before plain keywords (so `model {` is a block),
- * operator words before keywords (`is`, `not`), variables before value domains
- * (so `source`/`target` stay variables even though `RankValue` reuses `source`).
- *
- * @param {import('./langium.mjs').Vocabulary & { control: string[], variables: string[] }} vocabulary
- */
-function keywords(vocabulary) {
-	/** @type {Record<string, unknown>[]} */
-	const patterns = [];
-
-	const blocks = alternationOf(vocabulary.blocks);
-	if (blocks) {
-		patterns.push({
-			comment: 'Keywords that open a block: `model { … }`.',
-			name: 'keyword.control.block.likec4',
-			match: `\\b(?:${blocks})\\b(?=\\s*\\{)`,
-		});
-	}
-
-	// Blocks repeat in the keyword list on purpose: `predicateGroup mine { … }`
-	// is not followed by `{`, and still has to colour as a keyword. The block
-	// pattern above wins wherever the brace is there.
-	const control = alternationOf([...vocabulary.keywords, ...vocabulary.control, ...vocabulary.blocks]);
-
-	// Word operators (`is`, `not`) come before the keyword list, which also
-	// contains them: `where tag is #x` reads as an operator, not a keyword.
-	patterns.push({
-		name: 'keyword.operator.word.likec4',
-		match: `\\b(?:${alternationOf(OPERATOR_WORDS)})\\b`,
-	});
-
-	if (control) {
-		patterns.push({ name: 'keyword.control.likec4', match: `\\b(?:${control})\\b` });
-	}
-
-	const variables = alternationOf(vocabulary.variables);
-	if (variables) {
-		patterns.push({ name: 'variable.language.likec4', match: `\\b(?:${variables})\\b` });
-	}
-
-	const properties = alternationOf(vocabulary.properties);
-	if (properties) {
-		patterns.push({ name: 'support.type.property-name.likec4', match: `\\b(?:${properties})\\b` });
-	}
-
-	const values = alternationOf(uniqueDomain(vocabulary, VALUE_DOMAINS));
-	if (values) {
-		patterns.push({ name: 'constant.language.likec4', match: `\\b(?:${values})\\b` });
-	}
-
-	return { patterns };
-}
-
-function numbers() {
-	return { name: 'constant.numeric.likec4', match: '\\b\\d+(?:\\.\\d+)?%?' };
-}
-
-/**
- * Relationship connectors, longest first so `]->` wins over `->`.
- * @param {string[]} arrows
- */
-function operators(arrows) {
-	const patterns = [];
-
-	const connectors = alternationOf(arrows);
-	if (connectors) {
-		patterns.push({ name: 'keyword.operator.arrow.likec4', match: connectors });
-	}
-
-	patterns.push({ name: 'keyword.operator.wildcard.likec4', match: '\\.\\*\\*|\\.\\*|\\*\\*|\\*' });
-
-	return { patterns };
-}
-
-function punctuation() {
-	return {
-		patterns: [
-			{ name: 'punctuation.section.block.begin.likec4', match: '\\{' },
-			{ name: 'punctuation.section.block.end.likec4', match: '\\}' },
-			{ name: 'punctuation.separator.comma.likec4', match: ',' },
-			{ name: 'punctuation.accessor.likec4', match: '\\.' },
-		],
-	};
-}
-
-// endregion
-
-// region helpers
-
-/**
- * Every value of the named domains, deduplicated and sorted. Missing domains
- * are skipped rather than failing: upstream is free to rename a rule, and a
- * renamed domain still reaches the grammar through `keywords`.
- * @param {import('./langium.mjs').Vocabulary} vocabulary
- * @param {string[]} names
- */
-function uniqueDomain(vocabulary, names) {
-	const values = names.flatMap((name) => vocabulary.enums[name] ?? []);
-
-	return [...new Set(values)].sort((a, b) => a.localeCompare(b));
-}
-
-/**
- * `['a', 'b']` -> `a|b`, escaped for a TextMate regex. Returns '' for an empty
- * list so callers can skip the pattern instead of emitting `\b(?:)\b`.
- * @param {string[]} values
- */
-function alternationOf(values) {
-	return values.map(escapeRegExp).join('|');
-}
-
-function escapeRegExp(value) {
-	return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
-// endregion
-
-export default buildTmLanguage;
-

package/src/index.d.mts

@@ -1,64 +0,0 @@
-// index.d.mts
-// path: src/index.d.mts
-// Types for src/index.mjs. TypeScript does not read JSDoc from a package under
-// node_modules, so a site's astro.config.mjs needs these to type-check.
-
-import type { StarlightPlugin } from '@astrojs/starlight/types';
-import type { LikeC4VitePlugin } from 'likec4/vite-plugin';
-
-/**
- * LikeC4 syntax highlighting, derived from the Langium grammar in
- * `likec4/likec4` and registered with the site's Expressive Code.
- */
-export interface LikeC4HighlightingOptions {
-	/**
-	 * Branch, tag or commit SHA to read `like-c4.langium` from.
-	 * Defaults to `main`; pin a tag (`v1.59.4`) or a SHA for reproducible CI.
-	 * Also read from `ASTROC4_REF`.
-	 */
-	ref?: string;
-	/** Repository to read from. Defaults to `likec4/likec4`. */
-	repo?: string;
-	/** Use the bundled snapshot and never touch the network. Also `ASTROC4_OFFLINE=1`. */
-	offline?: boolean;
-	/**
-	 * What to do when the grammar cannot be fetched. Defaults to `fail`, so
-	 * `astro build` and `astro check` fail like any other build error.
-	 * A `ref` that does not exist always fails.
-	 */
-	onError?: 'fail' | 'warn' | 'silent';
-	/** Seconds a cached fetch stays fresh. Defaults to an hour. */
-	cacheTtl?: number;
-	/** Ignore the cache and refetch. */
-	refresh?: boolean;
-	/** Where to cache. Defaults to `node_modules/.cache/astroc4`. */
-	cacheDir?: string;
-	/** Raw host to read from, for mirrors. Defaults to raw.githubusercontent.com. */
-	baseUrl?: string;
-	/** Request timeout in milliseconds. Defaults to 15000. */
-	timeout?: number;
-}
-
-export interface StarlightLikeC4Options {
-	/**
-	 * Passed through to `LikeC4VitePlugin` — e.g. `{ workspace: 'diagrams' }` to
-	 * look for .c4 files somewhere other than the site root.
-	 */
-	vitePlugin?: Parameters<typeof LikeC4VitePlugin>[0];
-	/** Render ```likec4 fences in .mdx pages as diagrams. Defaults to `true`. */
-	fences?: boolean;
-	/**
-	 * Highlight ```c4 / ```likec4 source. Defaults to `true`; `false` leaves
-	 * Expressive Code entirely to the site.
-	 */
-	highlighting?: boolean | LikeC4HighlightingOptions;
-}
-
-export default function starlightLikeC4(options?: StarlightLikeC4Options): StarlightPlugin;
-
-/** Adds the LikeC4 language to a site's Expressive Code options, preserving the rest. */
-export declare function withLikeC4Language(
-	expressiveCode: unknown,
-	registration: Record<string, unknown>,
-): Record<string, unknown> & { shiki: { langs: unknown[] } };
-