feat(data): narrow an app's tables to the columns it refers to

[david-hudec-networg]

Stacked on #190 → #191 → #192. Only the last commit belongs to this PR. GitHub cannot express a cross-fork stack, so the base has to be master. Review in order.

What it does

--app narrows a conversion to the tables an app is built on. This narrows those tables to the columns something in the app refers to.

txc data model convert --root . --root ../TALXIS --app ntg_projectmanagement \
                       --columns-used --scan-code --target dbml

Both flags are opt-in and off by default.

How the search works

Rather than parse each artefact type, it searches for the column names it already knows. By the time the filter runs the column set is settled, so the only question is which of those names appear anywhere in forms, views, workflows, sitemaps — and, with --scan-code, .cs/.ts sources.

That makes the scan indifferent to artefact schemas (cloud-flow JSON in particular has no fixed shape for "which attribute"), and it errs toward keeping a column: a name shared by two tables keeps the column on both. For a feature whose failure mode is a missing column, over-keeping is the right direction to be wrong in.

Entity declarations are excluded. An entity declares its own columns, so reading one would report every column as referenced by itself — a filter that looks like it works and does nothing.

The rule that must not break

A column an edge depends on is kept regardless, alongside every primary key.

EDMXTranslator and SQLTranslator read Relationship.LeftSideRow / RighSideRow without a null check, so dropping one does not produce a narrower diagram — it crashes. All five targets were run with filtering on across three solutions to confirm it holds, and a test asserts the translators render after filtering rather than only asserting the column survived.

--scan-code

Plug-in and client-script sources sit outside the declarations, so they are structurally invisible to the default scan. Measured across three solutions: 58 / 114 / 105 distinct attribute literals live in .cs/.ts, and none of those files is under a Declarations folder.

On one app the flag keeps 89 columns that would otherwise be dropped — the measure of how wrong the narrow scan would have been.

It is separate and off by default because it makes a solution converter read source files, which is a real scope expansion and worth an explicit opt-in rather than a surprise.

Nothing is dropped quietly

Each removed column is reported, and the run states which surfaces were searched and which were not. A dropped column is one no reference was found for, which is not the same as one that is unused — a name built at runtime cannot be found at all. That wording is in --help, in the log line, and in the returned report.

Measured

One app, ntg_projectmanagement, project root plus product root:

	tables	columns
--app only	70	883
+ --columns-used	70	727
+ --scan-code	70	816

Five targets × three solutions with filtering on: all exit 0, no crashes. Every output parses with @dbml/core.

Guards

--columns-used without --app, and --scan-code without --columns-used, both fail with a message explaining the dependency (exit 2 via ArgumentException, per the base command's contract).

Tests

tests/TALXIS.CLI.Tests/Data/DataModelConverter/ColumnScopeTests.cs — six tests: a form reference keeps a column and an unreferenced one is dropped and reported; the primary key is never dropped; a relationship's column survives and the SQL/EDSSQL/EDMX targets still render; a column only a plug-in mentions is dropped without --scan-code and kept with it; an entity declaration does not count as a reference to its own columns; and without the flag columns are left alone.

29 converter tests green across the stack.

🤖 Generated with Claude Code

[david-hudec-networg]

Superseded by #194, which carries this wholesale rather than stacking on it.

The mechanism here resolves a reference by name against one global set, so a single occurrence of createdon anywhere keeps the column on every table that declares it — measured at 19 of 19 tables in a real app, from the views of three. That is a fair approximation for an author's column, which one table declares. It is not one for a platform column, whose name is identical on every table in the org, where it over-keeps every time.

#194 attributes each reference to the table whose artefact made it and retires --columns-used / --scan-code in favour of --detail full|minimal. Merging this first would introduce two flags and remove them one PR later, so it is closed instead of stacked.

What is kept from here, unchanged: the guardrail that a primary key and any column an edge depends on survive regardless, the Entity.xml exclusion, code scanning, and the wording that a dropped column is one no reference was found for — which is not the same as one that is unused.