feat: implement composer classmap autoloading (#49)

[KorsarOfficial]

Problem

KPHP's Composer autoloader supports PSR-0, PSR-4, and autoload/files, but not autoload/classmap. Packages using classmap (common for legacy or non-PSR code) silently fail, producing class not found compile errors.

Design Decision: Reusing KPHP's Lexer

The classmap strategy requires scanning PHP files to discover which classes they declare. Rather than writing a custom parser, this implementation reuses KPHP's own lexer via php_text_to_tokens() — the same tokenizer used by the compiler pipeline.

Why the lexer and not the full parser?

The classmap scanner runs during init_composer_class_loader(), before the compilation pipeline starts. At this stage we only need class names — not full AST nodes, type inference, or semantic analysis. The lexer is the minimal sufficient tool:

• It correctly handles all PHP syntax: strings, heredoc, block/line comments, escape sequences
• It produces typed tokens (tok_namespace, tok_class, tok_interface, tok_trait, tok_func_name) — no fragile string matching needed
• lexer_init() is guaranteed to run before init_composer_class_loader() in the startup sequence (compiler.cpp:202 vs :234)
• The scanner is ~30 lines vs ~120 for a hand-rolled heuristic approach

Formal Analysis: Autoload Resolution Chain

Define the autoload resolution as a priority-ordered function:

resolve : ClassName -> FilePath | _|_

resolve(n) = PSR4(n) (+) PSR0(n) (+) CM(n) (+) Default(n)

where (f (+) g)(x) = f(x) if f(x) != _|_, else g(x)

Classmap construction — built at load time by tokenizing files from composer.json paths:

tokens(f) = php_text_to_tokens(read(f))

declarations(f) = { ns_prefix + name :
    tok_i in {tok_class, tok_interface, tok_trait},
    tok_{i+1} = tok_func_name with str_val = name }

M = Union_i { (cls, f) : f in files(p_i), cls in declarations(f) }

CM(name) = M[name] if name in dom(M), else _|_

Complexity:

• Build: O(total_source_bytes) — one-time lexer pass at startup
• Lookup: O(1) average (hash map) vs PSR-4's O(P*D) with filesystem probes

Implementation

File	Change
compiler/data/composer-json-data.h	AutoloadClassmapEntry struct + autoload_classmap vector
compiler/data/composer-json-data.cpp	Parse classmap key in parse_composer_json_autoload()
compiler/composer.h	classmap_lookup() method + autoload_classmap_ map
compiler/composer.cpp	Token-based collect_php_class_names() via php_text_to_tokens() + scan_classmap_path() + classmap_lookup()
compiler/pipes/collect-required-and-classes.cpp	Insert classmap_lookup() after psr0_lookup()

Tests

• tests/python/tests/composer/php/test_autoload_classmap/ — fixture with classmap-based package
• test_classmap_autoloading in test_composer.py — end-to-end build-and-compare test

Technical Report

Full report with mathematical formalization (PDF)

Closes #49