codebase-map

Analyse a local tool codebase and map it against the feature model dimensions.

Inputs

The user provides a path to a local codebase directory, e.g.:

../extracted-codebases/Mono2Micro

Derive the tool name from the directory name.

Output files

Three files are produced per tool:

1. evaluation/analyses/<tool-name>/analysis.md — filled Analysis Template, feature coverage table, Observations
2. evaluation/analyses/<tool-name>/README.md — how to set up and run the tool, gotchas, pointer to the colour profile
3. feature_model/representation/.profiles/<tool-name>.profile — FeatureIDE colour profile for the canonical feature model

Never modify my_paper/text.md, feature_model/representation/feature_model.xml, any existing analysis, or any existing profile.

“Existing analysis” and “existing profile” mean files present in the working tree right now. Do not consult git, HEAD, or repository history to decide whether a file exists — judge only by what is on disk. If the user has deleted a tool’s analysis/README/profile locally to re-run the skill, those files do not exist and must be regenerated freely (overwrite is expected). Only refuse to modify analysis/profile files for other tools that are still present on disk.

Procedure

Step 1 — Explore the codebase structure

Get a high-level overview:

find <path> -maxdepth 3 -type f | head -80

Also look for:

• README.md or any documentation files at the root
• Build files (pom.xml, build.gradle, requirements.txt, package.json, etc.)
• Main entry points (main.*, app.*, run.*)
• Configuration files

Read the README and any top-level documentation.

Step 2 — Identify feature model coverage

For each feature model dimension, search the codebase for evidence of support. Use grep, find, and Read on relevant files.

Key dimensions to investigate (see references/feature-model-dimensions.md for the full schema):

Granularity: What unit does the tool decompose? Look for terms like class, method, entity, service, package, endpoint, file.

Representation Collection:

• What sources does it read? (source code files, DB schemas, logs, configs)
• What technique? (AST parsing → static; log parsing → dynamic; git history → version)

Representation (Syntax):

• What graph/model is built? (call graph, dependency graph, co-change graph)
• Is it structural, behavioural, or evolution-based?

Refactorization:

• What clustering/decomposition algorithms are used?
• Is there any manual editing support?
• What aggregation criteria drive the clustering?

Quality Assessment:

• What metrics are computed? (coupling, cohesion, MoJoFM, etc.)
• Is there any visual comparison support?

Also check for cross-tree constraint violations (see references/feature-model-dimensions.md). The most common one: Community detection → NOT Expert knowledge. Flag any violations in both the analysis and the colour profile. A violation occurs when the tool uses both features together despite the constraint forbidding it, or when the tool uses a feature without the other feature that must co-exist with it (e.g., dynamic analysis requires runtime).

Also look actively for model gap candidates — things present in the codebase that have no counterpart in the feature model schema. For each one, note: what it is, where it appears (file:line), whether it would be a leaf or group and under which parent. Pay particular attention to:

• Manual Editing operations beyond Merge/Split/Transfer (e.g., Rename cluster, Form cluster from selection)
• Quality Assessment metrics beyond the listed ones (e.g., silhouette score, performance/response-time, purity against expert)
• Refactorization post-processing steps not covered (e.g., contract generation, CML export)
• Representation sources or collection techniques not in the schema
• Visualisation capabilities not covered by Relations or Visualization Elements

Step 3 — Fill the Analysis Template

Read references/analysis-template.md and fill every section with findings from the codebase. Use bullet points. Every finding must cite at least one file:line reference from the actual codebase (e.g., src/main/Analyzer.java:42). If the only evidence is in documentation files (README, wiki, etc.), you may cite those, but label them explicitly (e.g., README.md — "…") and keep searching for a corroborating code reference. Never substitute a documentation quote for a code reference when the code contains the evidence.

Citation rules:

• Standard: `path/to/file.ext:line`
• Documentation only: `README.md — "quote"` — label it explicitly as documentation.
• Jupyter notebooks: `<notebook>.ipynb` Cell N, lines X–Y (e.g., `1-System_analysis.ipynb` Cell 22, lines 242–260).
• No evidence: write [evidence not found].

Step 4 — Build the feature coverage table

Produce a table with every leaf feature from the model:

Use Unclear when there is indirect evidence but no direct confirmation.

Evidence format rules (in order of preference):

1. Actual codebase reference: `path/to/file.ext:line` — always preferred.
2. Documentation reference: `README.md — "quote"` — allowed only when no code reference exists; must be labelled as documentation.
3. Both: when documentation and code both support a finding, include the code reference and optionally add the documentation reference in parentheses.
4. Unclear: when there is indirect evidence but no direct confirmation — cite the best available reference and note why it is indirect.

Never write a documentation reference in place of a code reference when the code contains the evidence. When a feature is evidenced by both a README claim and an actual code/data artifact (e.g., a CSV file, an AST node, a solver object), cite the artifact — it is more informative and more trustworthy than a documentation quote.

Step 5 — Write the Observations section

Add a section with the following subsections:

Model Gap Candidates — things present in the codebase that have no counterpart in the feature model. For each candidate use this format:

• Name — what it would be called as a feature
• Would be: leaf or group, and the parent dimension/group it would sit under
• Evidence: file:line
• Rationale: one sentence on why it warrants a place in the model

Other features outside the model — features that are present in the codebase but not captured by the feature model and don’t meet the criteria to be a model gap candidate (e.g., they are too specific, too low-level, or not relevant to the paper’s scope). For each one, note what it is and where it appears.

Model Vocabulary Fit — dimensions where the model’s vocabulary doesn’t quite match the tool’s design (concept mismatch, partial overlap, etc.).

Cross-tree constraint violations — features that are used together but the model forbids it (or mandatory co-features that are missing).

Noteworthy design decisions — interesting patterns, architectural choices, or limitations worth mentioning in the paper’s evaluation narrative.

Step 6 — Write analysis.md

Create evaluation/analyses/<tool-name>/ and write analysis.md with sections:

# Analysis — <tool-name>

Codebase path: <path>
Date: <today's date>

---

## Filled Analysis Template
[content from Step 3]

---

## Feature Coverage Table
[table from Step 4]

---

## Observations

### Model Gap Candidates
[candidates from Step 5]

### Other features outside the model
[list from Step 5]

### Model Vocabulary Fit
[vocabulary notes from Step 5]

### Cross-tree constraint violations
[violations from Step 5, or "None found."]

### Noteworthy design decisions
[design notes from Step 5]

Step 7 — Write README.md

Write evaluation/analyses/<tool-name>/README.md with the following structure:

# <Tool Name>

<one-line description — tool purpose and paper venue/year>

## Relevant Files

| File | Description |
|------|-------------|
| [<Paper title> (<Venue> <Year>)](../../papers/tools/<Tool>.pdf) | Paper PDF |
| [analysis.md](./analysis.md) | Feature model coverage analysis |
| [feature_model/representation/.profiles/<tool-name>.profile](../../feature_model/representation/.profiles/<tool-name>.profile) | FeatureIDE colour profile |
| [../../../../extracted-codebases/<tool-name>](../../../../extracted-codebases/<tool-name>) | Extracted codebase |
| [evaluation/papers/<Survey>.md](../papers/<Survey>.md) | Tool inventory |

---

## Prerequisites
...

## How to Run
...

## Gotchas
...

Tool inventory row: The tool inventory file (evaluation/papers/<Survey>.md) is produced by extract-codebases-from-paper before codebase-map runs. Locate the correct inventory file by searching evaluation/papers/ for the .md file that lists this tool. Insert the relative link. After writing the README, verify the link resolves to an existing file.

Paper PDF path: If the paper PDF is in papers/tools/, use ../../papers/tools/<Tool>.pdf. If it is in a subdirectory like papers/mono2micro_process/, adjust accordingly. Check the path exists before writing.

Multiple repos (e.g. backend + frontend): Add one codebase row per repository.

Step 8 — Write the colour profile

Write feature_model/representation/.profiles/<tool-name>.profile. If this file is not on disk, write it — do not check git/HEAD first; a missing-on-disk profile is meant to be (re)generated.

The profile format is a flat key=value text file. The first line must be false. Feature names must match exactly the leaf and group names in feature_model/representation/feature_model.xml.

Colour scheme — leaves:

Note: Dark_Green is only valid for group nodes, never for leaves.

Colour scheme — groups (non-leaf nodes):

Rules for propagating colour up to groups (priority: Red > Orange > Magenta > Light_Green > Yellow):

1. Evaluate each child first.
2. If the group is mandatory and any mandatory child is Red → group is Red.
3. Else if any child is Orange → group is Orange.
4. Else if any mandatory child is Magenta — or, for an OR group, the only present child(ren) are Magenta (every confirmed branch is absent/Red) → group is Magenta. Uncertainty in a required child propagates up; confirmed sibling leaves do not rescue the group.
5. Else if ≥1 mandatory child is confirmed present (Light_Green/Dark_Green) — or, for an OR group, ≥1 child is confirmed present — and no mandatory child is missing or Magenta → group is Light_Green (OR) or continue evaluating (AND).
6. For AND groups: if all mandatory children are fully satisfied and no violations → Dark_Green. A child is fully satisfied when it is a leaf that is present (Light_Green — a leaf’s max, since leaves are never Dark_Green) or a group that is itself Dark_Green. A mandatory child group that is only Light_Green (partially satisfied) caps the AND parent at Light_Green. (Optional children that are absent or Magenta do not block Dark_Green; an optional Red/Orange child still applies rule 2/3.)
7. Optional group with zero present children → Yellow.

Include every leaf and group feature name from feature_model/representation/feature_model.xml. End the file with the following legend keys:

featureColorMeaning0=Leaf/Group: absent or broken (mandatory)
featureColorMeaning1=Constraint violation
featureColorMeaning2=Leaf/Group: absent (optional)
featureColorMeaning3=Group: fully satisfied
featureColorMeaning4=Leaf: exists / Group: partially satisfied
featureColorMeaning5=Extra Feature
featureColorMeaning6=InvalidColor (unused in FeatureIDE)
featureColorMeaning7=InvalidColor (unused in FeatureIDE)
featureColorMeaning8=Leaf: unclear / indirect evidence
featureColorMeaning9=InvalidColor (unused in FeatureIDE)

Step 9 — Report to the user

Summarise:

• Which dimensions had strong coverage vs. gaps
• Any constraint violations found
• Anything particularly noteworthy from the Observations
• Paths to the three output files

Reference files

• references/feature-model-dimensions.md — full feature model schema with cross-tree constraints
• references/analysis-template.md — the template to fill in Step 3
• feature_model/representation/feature_model.xml — canonical feature model (leaf names for the colour profile)
• feature_model/representation/.profiles/ — existing profiles for reference on format