lint: an include fragment analyzed as a root reports every symbol its includer supplies as undefined

[evanbrobertson]

An .i file is a fragment: the symbols it uses are frequently declared by a sibling include that the including program pulls in, not by anything the fragment itself references. The CLI never notices, because .i is never a root in the discovery policy. The editor analyzes whatever file is open, so opening an include produces a wave of undefined-symbol errors on code that compiles.

The same code is therefore silent through the gate and noisy in the editor — not because the pipeline differs, but because each client feeds it a different kind of input.

Repro

/* helpers.i — included by the program before the fragment below */
FUNCTION fetch-param RETURNS CHARACTER (INPUT pName AS CHARACTER):
    RETURN "".
END FUNCTION.

/* fragment.i — real logic, no declarations of its own */
sContentType = TRIM(fetch-param("content":U)).

/* program.p — the root */
{helpers.i}
{fragment.i}

oxabl check program.p is clean. oxabl check fragment.i reports undefined symbol fetch-param``, and so does the editor the moment fragment.i is opened.

Scale

Measured on a large real-world ABL codebase kept outside this repo, sampling 40 include files: 24 of 40 carried at least one LINT0001, 709 findings across the sample. Include files outnumber root files there, so the in-editor volume from this exceeds the entire root walk's LINT0001 count by several times. Any codebase that keeps logic in includes — web/CGI-style ABL especially — hits it constantly.

The shape of the fix, and the reason model already has the vocabulary

An unresolved name in a fragment is not absent. It is not knowable from here: the declaring context is whichever program includes this file, and oxabl is not looking at one. That is the distinction UnresolvedReason already draws — External means "we did not look", and every rule skip-lists it, while AbsentFromWorkspace means "we searched and it is not there" and is the only cross-file reason undefined-symbol reports.

So the candidate fix is to analyze a file opened as an .i in a mode where a name that fails locally is External rather than reported, and to say so, rather than to suppress a rule per-symbol. Options considered:

1. Fragment mode — a root-position .i yields External for names it cannot resolve. Keeps parse, format and every scope-independent rule working while declining to claim what it cannot know. Preferred: it reuses the existing reason model rather than adding a suppression, and it is honest instead of silent.
2. No diagnostics for .i at all — exactly matches the CLI root policy, but loses all feedback while editing an include, which is a real capability loss where logic lives in includes.
3. Infer an including context and analyze the fragment through it. Best answers, but a fragment may have many includers with conflicting contexts, and picking one silently invents a scope.
4. Report at reduced severity — leaves the noise, just quieter.

Whichever is chosen, the acceptance criterion is the asymmetry: the same include should not be clean through check and covered in errors in the editor.

Notes

Surfaced during in-editor dogfood, which is the loop STRATEGY.md says exists to catch trust-eroding false positives that corpus runs cannot — the corpus walk reports zero of these by construction. Pre-existing and independent of cross-file resolution.

Related: #142 (a nested unresolvable include drops its PREPROC007) is the neighbouring include-visibility gap, and #143 (make the root extension set configurable) touches the same root-vs-fragment policy.

[evanbrobertson]

A second instance found in the same dogfood session, which broadens the scope of this beyond the original example.

The first case was a FUNCTION declared in a sibling include. This one is a shared variable declared in a global include — the classic ABL idiom where a project keeps its Def new shared var declarations in one or two includes that every program pulls in first:

/* globals.i — every program includes this */
DEFINE NEW SHARED VARIABLE subsys AS CHARACTER FORMAT "x(2)".

/* fragment.i — real logic, includes nothing */
subsys = "ap":U.

Open the program: clean. Open fragment.i: error[LINT0001]: undefined symbol subsys``.

Measured on the same codebase: of twelve include files sampled that assign such a variable, nine report it as an undefined symbol. So this is not one unlucky helper — it is every include that touches a project global, which in a codebase organized this way is most of them.

Two things this changes about the issue above:

The affected population is larger than "functions from includes." Global/shared variable declarations are the most common thing an ABL include provides, so the fragment problem lands hardest on exactly the idiom the language encourages.

The External framing in option 1 is necessary but may not be sufficient. It covers a name that does not resolve, which is this case and the original one. It does not cover a name that resolves inside the fragment while its counts are incomplete — a variable written in the fragment whose readers live in the including program will resolve fine and then look like a dead store to LINT0006, with no unresolved reason anywhere to mark. Worth deciding whether fragment mode also withholds the count-gated rules (LINT0002/0005/0006), or whether that is a separate follow-up. Either way it should be a deliberate decision rather than discovered later.

Note this is not the shared_producer cross-file path: ABL requires each program to carry its own DEFINE SHARED VARIABLE, so the declaration genuinely arrives through the include, not from whichever program defined it NEW.