crosseno/clues

Language-neutral clue selection, validation, and deterministic assignment for Crosseno crosswords.

dev-main 2026-07-19 14:48 UTC

Requires

• php: ^8.5
• ext-mbstring: *
• crosseno/core: ^0.1
• crosseno/lexicon: ^0.1

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.95
• phpstan/phpstan: ^2.2
• phpunit/phpunit: ^12.5

MIT

Published on Packagist.org on 2026-07-26 18:59 UTC

README

Language-neutral clue selection, validation, and deterministic assignment for Crosseno crosswords.

The package provides bounded clue lookup, validation, scoring, selection, and post-placement assignment.

Installation

composer require crosseno/clues

The local workspace uses path repositories for the sibling crosseno/core and crosseno/lexicon packages. Published releases use the tagged ^0.1 constraints.

Usage

use Crosseno\Clues\Assignment\ClueAssignmentConstraints;
use Crosseno\Clues\Assignment\ClueSeed;
use Crosseno\Lexicon\Language\LanguageCode;

$result = $assigner->assign(
    $generatedCrossword,
    $clueCatalog,
    new ClueAssignmentConstraints(new LanguageCode('en'), targetDifficulty: 50),
    new ClueSeed('publication-2026-07-17'),
);

Catalogs implement ClueProviderInterface and return bounded results for a sense, language policy, and allowed types. The assigner validates every candidate, ranks valid clues with integer scores, uses a versioned SHA-256 tie order, prevents repeated IDs/text, then validates the complete set.

A runtime language pack's storage-neutral lexical catalog can be adapted directly:

use Crosseno\Clues\Catalog\LexicalCatalogClueProvider;

$provider = new LexicalCatalogClueProvider(
    $runtimePack->catalog(),
    $runtimePack->metadata()->stableKeyAlgorithmVersion,
);

The adapter requires a stable sense-key query, applies the requested language-matching policy and type filter, preserves stable IDs, bounds results, and returns clue-ID order. Catalog records with missing required difficulty or unsupported domain data fail explicitly. See catalog provider.

Clue text is plain UTF-8 text. HTML is never trusted or interpreted by this package; renderers must escape it for their output context. Construction and assignment policies independently enforce byte and Unicode-code-point limits.

Language services and validation

Leakage policy explicitly chooses display text, normalized tokens, lemmas, or supplied inflected forms, plus whole-token or substring matching. Normalization and lexical equivalence come from crosseno/lexicon interfaces through LanguageServiceProviderInterface. Missing services and missing sense mappings have explicit fail-closed or opt-out policies.

The standard validators cover answer leakage, same-root leakage, unsupported/ambiguous senses, language mismatch, length, difficulty, duplicates, missing clues, and set-level difficulty balance.

Boundaries

Assignment runs only after placement. The package does not query clue text in generator search, render HTML, depend on a concrete language pack, expose SQLite records, or provide CMS container/routing configuration.

Ordinary applications normally receive the standard assigner through crosseno/builder; direct use remains available for custom policy. The English executable proof is crosseno/builder/examples/generate-english.php.